audio-espresso-helper/README.md

Local helper tool for Audio Espresso - downloads YouTube audio and uploads to your account

# 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

```bash
# 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

```bash
# 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:

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

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

### Process YouTube URLs

```bash
# 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

```bash
audio-espresso status
```

## 📖 Commands

### `setup`

Configure API connection and authentication

```bash
audio-espresso setup [options]

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

### `process`

Download and upload YouTube audio

```bash
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

```bash
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:

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

### Using yt-dlp

```bash
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`:

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

## 🐛 Troubleshooting

### "Not configured" Error

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

### "yt-dlp not found"

```bash
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:
```bash
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

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

### With Cookies

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

### Batch Processing

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

### Keep Files

```bash
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

```bash
# 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](../BYOF_GUIDE.md) or check `audio-espresso status`.

---

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