npm package: @glucktek/n8n-nodes-youtube-cut-audio
Description: YouTube Audio Extractor - Extract and cut audio clips from YouTube videos with custom timestamps. Uses YouTube.js (pure JavaScript) and bundled ffmpeg - no Python or yt-dlp required!
Author: GluckTek
Latest version: 2.1.0

# n8n-nodes-youtube-cut-audio

An n8n community node that downloads audio from YouTube videos and cuts it between specified timestamps. Uses **pure JavaScript** (YouTube.js) and bundled ffmpeg - no Python or yt-dlp required!

## ⚠️ Important Notes

**Reliability**: This package uses YouTube.js, a pure JavaScript library that accesses YouTube's internal API. While actively maintained, YouTube may occasionally block or change their API, causing temporary failures. The node includes automatic retry logic and helpful error messages.

**Legal**: Downloading YouTube content may violate YouTube's Terms of Service. Use this node responsibly and only for content you have permission to download.

## Features

- ✅ Download audio from YouTube videos using pure JavaScript (no Python required)
- ✅ Cut audio between configurable start and end timestamps
- ✅ Support for multiple audio formats (M4A, MP3, Opus)
- ✅ Returns audio as binary data for use in n8n workflows
- ✅ Includes JSON metadata (URL, timestamps, format, filename)
- ✅ **Zero system dependencies** - ffmpeg binary is automatically included
- ✅ Automatic retry logic (3 attempts with exponential backoff)
- ✅ Helpful error messages when YouTube blocks requests

## Installation

### For n8n Users (Non-Docker)

Simply install the node package into your n8n installation:

```bash
npm install --prefix ~/.n8n @glucktek/n8n-nodes-youtube-cut-audio
```

Restart n8n to load the new node.

### For Docker/Docker Compose Users

**Option 1: Install via n8n UI**
1. Go to Settings → Community Nodes
2. Search for `@glucktek/n8n-nodes-youtube-cut-audio`
3. Click Install
4. Restart your n8n container

**Option 2: Install via Environment Variable**

Add to your docker-compose.yml:

```yaml
version: '3.8'
services:
  n8n:
    image: n8nio/n8n:latest
    ports:
      - "5678:5678"
    environment:
      - N8N_COMMUNITY_PACKAGES=@glucktek/n8n-nodes-youtube-cut-audio
    volumes:
      - n8n_data:/home/node/.n8n
volumes:
  n8n_data:
```

**Option 3: Manual Installation in Container**

```bash
# Access the container
docker exec -it n8n-container bash

# Install the package
cd /home/node/.n8n
npm install @glucktek/n8n-nodes-youtube-cut-audio

# Restart the container
exit
docker restart n8n-container
```

## Usage

### Node Parameters

| Parameter | Type | Required | Default | Description |
|-----------|------|----------|---------|-------------|
| YouTube URL | String | Yes | - | The YouTube video URL (e.g., https://www.youtube.com/watch?v=...) |
| Start Time | String | Yes | - | Start time in ffmpeg format (e.g., "00:01:23" or "83.5") |
| End Time | String | No | - | End time in ffmpeg format. If empty, cuts from start to end |
| Audio Format | Options | Yes | m4a | Output format: M4A, MP3, or Opus |
| Output File Name | String | No | - | Custom filename (without extension). Default: random UUID |

### Time Format Examples

The start and end time parameters accept various formats:

- Seconds: `"83.5"`
- MM:SS: `"01:23"`
- HH:MM:SS: `"00:01:23"`
- With milliseconds: `"00:01:23.500"`

### Output

The node outputs:

**Binary Data** (stored in `binary.data`):
- The cut audio file in the specified format

**JSON Metadata**:
```json
{
  "youtubeUrl": "https://www.youtube.com/watch?v=...",
  "start": "00:01:23",
  "end": "00:05:45",
  "format": "m4a",
  "outputFileName": "cut-abc123.m4a"
}
```

### Example Workflow

Here's a simple example workflow:

1. **Manual Trigger** - Start the workflow manually
2. **Set** - Define the YouTube URL and timestamps:
   ```json
   {
     "url": "https://www.youtube.com/watch?v=dQw4w9WgXcQ",
     "start": "00:00:10",
     "end": "00:00:30"
   }
   ```
3. **YouTube Cut Audio** - Configure the node:
   - YouTube URL: `{{ $json.url }}`
   - Start Time: `{{ $json.start }}`
   - End Time: `{{ $json.end }}`
   - Audio Format: `mp3`
4. **Action Node** - Use the audio binary data:
   - Return via Webhook Response
   - Upload to S3/Google Drive/Dropbox
   - Send as email attachment
   - Process further with other audio nodes

### Advanced Usage

**Batch Processing**: The node processes each input item, so you can pass multiple YouTube URLs with different timestamps in a single execution.

**Error Handling**: Enable "Continue on Fail" in the node settings to handle errors gracefully when processing multiple items.

**Format Selection**:
- Use **M4A** for best compatibility with Apple devices (smallest file size with codec copy)
- Use **MP3** for universal compatibility (re-encodes audio)
- Use **Opus** for modern, high-quality audio (good compression)

## Troubleshooting

### Download Fails

**"Failed to download audio from YouTube"**

This can happen due to:
1. **YouTube's anti-bot protection** - The node includes retry logic, but YouTube may still block requests
2. **Region restrictions** - Video may not be available in your region
3. **Private/age-restricted videos** - These require authentication
4. **Unavailable videos** - Video has been deleted or made private

**Solutions**:
- Wait a few minutes and try again
- Try a different video to verify the node works
- Check if the video is available in your region
- Ensure the video is public and not age-restricted

### YouTube.js Library Updates

YouTube frequently changes their internal API. If downloads suddenly stop working:

1. Check for package updates:
   ```bash
   npm update @glucktek/n8n-nodes-youtube-cut-audio
   ```

2. Check the [GitHub issues](https://github.com/glucktek/n8n-nodes-youtube-cut-audio/issues) for known problems

3. The YouTube.js library is actively maintained and usually fixes issues within days

### Audio Cutting Issues

**"Failed to cut audio with ffmpeg"**

- Verify your timestamp format is correct
- Check that start time is less than end time
- Ensure the downloaded audio file isn't corrupted (check n8n logs)

### Package Size

- The package includes platform-specific ffmpeg binaries (~60-100MB)
- Only the binary for your platform is used
- This ensures the node works anywhere without system dependencies

## Technical Details

### How It Works

1. **YouTube Download**: Uses [YouTube.js](https://github.com/LuanRT/YouTube.js) to access YouTube's InnerTube API
2. **Retry Logic**: Automatically retries failed downloads up to 3 times with exponential backoff
3. **Audio Cutting**: Uses bundled ffmpeg binary from [@ffmpeg-installer/ffmpeg](https://www.npmjs.com/package/@ffmpeg-installer/ffmpeg)
4. **Temporary Files**: Creates temp directory, processes audio, returns binary data, cleans up

### Dependencies

- **youtubei.js**: Pure JavaScript YouTube client (no Python/binaries needed)
- **@ffmpeg-installer/ffmpeg**: Platform-specific ffmpeg binaries
- **n8n-workflow**: n8n node development framework

### Why YouTube.js Instead of yt-dlp?

This package uses YouTube.js (pure JavaScript) instead of yt-dlp (Python) for:
- ✅ No Python installation required
- ✅ No system dependencies
- ✅ Works in any Node.js environment
- ✅ Easier deployment in Docker/cloud environments

**Trade-off**: YouTube.js may be less reliable than yt-dlp when YouTube makes API changes, but it's actively maintained and usually updated quickly.

## Development

### Build from Source

```bash
# Clone the repository
git clone https://github.com/glucktek/n8n-nodes-youtube-cut-audio.git
cd n8n-nodes-youtube-cut-audio

# Install dependencies
npm install

# Build TypeScript
npm run build

# The compiled output will be in dist/YoutubeCutAudio.node.js
```

### Local Testing

To test locally before publishing:

1. Build the package:
   ```bash
   npm run build
   ```

2. Create a tarball:
   ```bash
   npm pack
   ```

3. Install in your n8n instance:
   ```bash
   npm install --prefix ~/.n8n ./glucktek-n8n-nodes-youtube-cut-audio-2.1.0.tgz
   ```

4. Restart n8n

## Version History

### v2.1.0 (Latest)
- ✨ Switched from play-dl to YouTube.js for better reliability
- ✨ Added automatic retry logic (3 attempts with exponential backoff)
- ✨ Improved error messages with helpful suggestions
- ✨ Pure JavaScript - no Python/yt-dlp required
- 🐛 Fixed "Invalid URL" errors
- 📝 Updated documentation with realistic expectations

### v2.0.x
- Various attempts to use different YouTube download libraries
- play-dl, ytdl-core, etc. (deprecated)

### v1.x
- Initial release with yt-dlp wrapper
- Required Python system dependency

## License

MIT

## Contributing

Contributions are welcome! Please open an issue or submit a pull request.

## Author

GluckTek - contact@glucktek.com

## Links

- [GitHub Repository](https://github.com/glucktek/n8n-nodes-youtube-cut-audio)
- [npm Package](https://www.npmjs.com/package/@glucktek/n8n-nodes-youtube-cut-audio)
- [n8n Community Nodes Documentation](https://docs.n8n.io/integrations/community-nodes/)
- [YouTube.js](https://github.com/LuanRT/YouTube.js)
- [ffmpeg](https://ffmpeg.org/)