Audio Espresso Helper Tool

Download YouTube audio locally and upload to Audio Espresso for analysis

🎯 What This Does

This helper tool runs on your computer and:

1. Downloads audio from YouTube (using your cookies/authentication)
2. Uploads the audio file to Audio Espresso
3. Keeps your server out of YouTube's crosshairs

⚡ Quick Start

# Install
npm install

# Setup
npm link  # Makes 'audio-espresso' command available
audio-espresso setup --url http://localhost:3001

# Process a YouTube URL
audio-espresso process "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

📦 Installation

Prerequisites

• Node.js 14 or higher
• yt-dlp (will be installed with npm dependencies)

Install Steps

# 1. Install dependencies
npm install

# 2. Link globally (optional but recommended)
npm link

# 3. Verify installation
audio-espresso --version

🚀 Usage

Setup

Configure the helper to connect to your Audio Espresso instance:

# Local development
audio-espresso setup --url http://localhost:3001

# Production
audio-espresso setup --url https://api.audioespresso.com --token YOUR_TOKEN

Process YouTube URLs

# Basic usage
audio-espresso process "YOUTUBE_URL"

# With YouTube cookies (for restricted content)
audio-espresso process "YOUTUBE_URL" --cookies ~/cookies.txt

# Keep downloaded file
audio-espresso process "YOUTUBE_URL" --keep

# Custom output directory
audio-espresso process "YOUTUBE_URL" --output ~/Downloads

Check Status

audio-espresso status

📖 Commands

setup

Configure API connection and authentication

audio-espresso setup [options]

Options:
  -u, --url <url>      API URL
  -t, --token <token>  Auth token

process

Download and upload YouTube audio

audio-espresso process <url> [options]

Arguments:
  url                  YouTube URL

Options:
  -o, --output <dir>   Output directory (default: temp)
  -k, --keep           Keep file after upload
  --cookies <file>     YouTube cookies file

status

Check configuration and connection

audio-espresso status

🍪 YouTube Cookies

For age-restricted or private content, export your YouTube cookies:

Using Browser Extension

1. Install "Get cookies.txt" extension
2. Go to youtube.com (logged in)
3. Export cookies
4. Use with helper:

audio-espresso process "URL" --cookies ~/cookies.txt

Using yt-dlp

yt-dlp --cookies-from-browser chrome --cookies cookies.txt "https://www.youtube.com/"
audio-espresso process "URL" --cookies cookies.txt

🔧 Configuration

Config is stored in ~/.audio-espresso/config.json:

{
  "apiUrl": "http://localhost:3001",
  "authToken": "your-token-here"
}

🐛 Troubleshooting

"Not configured" Error

audio-espresso setup --url http://localhost:3001

"yt-dlp not found"

npm install  # Reinstall dependencies

"Connection failed"

1. Check backend is running
2. Verify API URL: audio-espresso status
3. Update if needed: audio-espresso setup --url CORRECT_URL

YouTube Bot Detection

Use your cookies:

audio-espresso process "URL" --cookies ~/cookies.txt

🎯 How It Works

Your Computer          YouTube              Audio Espresso
     │                    │                       │
     │  1. Download       │                       │
     ├───────────────────>│                       │
     │                    │                       │
     │  2. Audio file     │                       │
     │<───────────────────┤                       │
     │                                            │
     │  3. Upload file                            │
     ├───────────────────────────────────────────>│
     │                                            │
     │  4. Track ID                               │
     │<───────────────────────────────────────────┤
     │                                            │

📝 Examples

Basic Usage

audio-espresso process "https://www.youtube.com/watch?v=dQw4w9WgXcQ"

With Cookies

audio-espresso process \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --cookies ~/Downloads/youtube_cookies.txt

Batch Processing

#!/bin/bash
for url in $(cat urls.txt); do
  audio-espresso process "$url"
  sleep 2
done

Keep Files

audio-espresso process \
  "https://www.youtube.com/watch?v=VIDEO_ID" \
  --output ~/Music/AudioEspresso \
  --keep

🔐 Security

• Cookies are only sent to YouTube, never to Audio Espresso
• Auth token is stored locally in ~/.audio-espresso/
• Downloaded files are cleaned up by default
• All uploads use HTTPS (in production)

🚀 Development

# Run without installing
node index.js process "URL"

# Test mode
npm test

# Debug mode
DEBUG=* node index.js process "URL"

📦 Dependencies

• axios - HTTP client
• chalk - Terminal colors
• commander - CLI framework
• form-data - Multipart uploads
• ora - Loading spinners
• youtube-dl-exec - YouTube downloader

📄 License

MIT

🤝 Contributing

This is part of the Audio Espresso project. See main repository for contribution guidelines.

📞 Support

For help, see the main BYOF Guide or check audio-espresso status.

Version: 1.0.0
Author: Audio Espresso Team
Status: ✅ Production Ready