Audio Extractor API

A containerized REST API service for extracting full audio from YouTube videos using yt-dlp. Perfect for building walkup song applications where you need the complete audio file and can handle clipping on the frontend.

Features

• Extract full audio in multiple formats (MP3, M4A, WAV, FLAC)
• Multiple quality options (best, worst, 320k, 192k, 128k)
• Direct file download in single API call
• CORS protection with debug mode toggle
• Automatic file cleanup
• RESTful API with FastAPI
• Docker containerization
• Health checks and monitoring

Quick Start

1. Clone and navigate to the project directory
2. Set environment variables (see Configuration section)
3. Run with Docker Compose:

docker-compose up --build

The API will be available at http://localhost:8000

Configuration

Environment Variables

Variable	Description	Default	Example
DEBUG_MODE	Enable debug mode (allows all origins)	false	true
ALLOWED_ORIGINS	Comma-separated list of allowed frontend URLs	``	https://yourapp.com,https://www.yourapp.com
DOWNLOAD_DIR	Directory for downloaded files	/app/downloads	./downloads

Development Setup

# .env file for development
DEBUG_MODE=true
DOWNLOAD_DIR=./downloads

Production Setup

# .env file for production
DEBUG_MODE=false
ALLOWED_ORIGINS=https://walkupsongs.yourapp.com,https://yourapp.com
DOWNLOAD_DIR=/app/downloads

API Usage

Extract Audio Endpoint

Endpoint: POST /extract

Description: Downloads and extracts the full audio from a YouTube video, returning the file directly.

Request Body:

{
  "url": "https://youtu.be/xFrGuyw1V8s?feature=shared",
  "format": "mp3",
  "quality": "192",
  "output_filename": "dancing_queen"
}

Parameters:

• url (required): YouTube video URL
• format (optional): Audio format - "mp3", "m4a", "wav", "flac" (default: "mp3")
• quality (optional): Audio quality - "best", "worst", "320", "192", "128" (default: "192")
• output_filename (optional): Custom filename (default: uses video title)

Response: The audio file with metadata in headers:

• X-Title: Video title
• X-Duration: Duration in seconds
• X-File-Size: File size in bytes

cURL Example:

curl -X POST "http://localhost:8000/extract" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://youtu.be/xFrGuyw1V8s?feature=shared",
    "format": "mp3",
    "quality": "192",
    "output_filename": "dancing_queen"
  }' \
  --output dancing_queen.mp3

JavaScript Fetch Example:

const response = await fetch('http://localhost:8000/extract', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
  },
  body: JSON.stringify({
    url: 'https://youtu.be/xFrGuyw1V8s?feature=shared',
    format: 'mp3',
    quality: '192',
    output_filename: 'dancing_queen'
  })
});

if (response.ok) {
  const audioBlob = await response.blob();
  const audioUrl = URL.createObjectURL(audioBlob);

  // Get metadata from headers
  const title = response.headers.get('X-Title');
  const duration = response.headers.get('X-Duration');

  // Play specific segment (e.g., 1:27 to 1:45)
  const audio = new Audio(audioUrl);
  audio.currentTime = 87; // 1:27 in seconds
  audio.play();
  setTimeout(() => audio.pause(), 18000); // Stop after 18 seconds
}

Other Endpoints

Get Video Info: POST /info

{
  "url": "https://youtu.be/xFrGuyw1V8s"
}

Health Check: GET /health

API Documentation: GET /docs (Swagger UI)

Frontend Audio Clipping

Since this API returns full audio files, you can handle clipping on the frontend:

// Play from specific time
const audio = new Audio(audioUrl);
audio.currentTime = startTimeInSeconds;
audio.play();

// Stop at specific time
const clipDuration = endTimeInSeconds - startTimeInSeconds;
setTimeout(() => audio.pause(), clipDuration * 1000);

CORS Security

The API includes CORS protection:

• Development Mode (DEBUG_MODE=true): Accepts requests from any origin
• Production Mode (DEBUG_MODE=false): Only accepts requests from URLs listed in ALLOWED_ORIGINS
• No Configuration: Only accepts same-origin requests

The active CORS mode is logged on startup for verification.