Home - darkwob/youtube-mp3-converter GitHub Wiki

YouTube MP3 Converter

A powerful PHP library for converting YouTube videos to MP3 format with advanced features, enhanced Windows support, cross-platform compatibility, and intelligent binary management.

Key Features

  • 🎵 YouTube to MP3 Conversion: High-quality audio extraction
  • 🚀 Cross-Platform: Enhanced Windows support with path normalization
  • 📁 Intelligent Binary Management: Auto-detection with fallback options
  • ⚙️ Flexible Configuration: Custom paths, quality settings, metadata
  • 📊 Progress Tracking: Real-time conversion progress
  • 🔄 Modern PHP: Built for PHP 8.3+ with strict typing
  • 🛠️ Easy Integration: Simple API with powerful customization
  • 🪟 Windows Ready: Native Windows path handling and binary detection
  • 🔧 Advanced Error Handling: Specific exception types with helpful messages

Requirements

  • PHP: 8.3 or higher
  • External Tools (manual installation):
    • yt-dlp - YouTube video downloader
    • FFmpeg - Audio/video processing

Quick Start

1. Install via Composer

composer require darkwob/youtube-mp3-converter

2. Setup Binary Directory

Create a bin/ directory in your project root and place the required tools:

your-project/
├── composer.json
├── bin/                    # Create this manually
│   ├── yt-dlp.exe         # Windows
│   ├── yt-dlp             # Linux/macOS
│   ├── ffmpeg.exe         # Windows
│   └── ffmpeg             # Linux/macOS
└── src/

Download Links:

3. Basic Usage

<?php

use Darkwob\YoutubeMp3Converter\Converter\YouTubeConverter;
use Darkwob\YoutubeMp3Converter\Progress\FileProgress;

// Create converter (binaries auto-detected)
$converter = new YouTubeConverter(
    outputPath: './downloads',
    tempPath: './temp',
    progress: new FileProgress('./progress')
);

// Convert video
$result = $converter->processVideo('https://www.youtube.com/watch?v=VIDEO_ID');

echo "Converted: {$result->getTitle()}\n";
echo "File: {$result->getOutputPath()}\n";
echo "Size: " . round($result->getSize() / 1024 / 1024, 2) . " MB\n";

Binary Management

The library uses a flexible binary management system:

Automatic Detection

Place binaries in bin/ directory - they're detected automatically:

use Darkwob\YoutubeMp3Converter\Converter\Util\PlatformDetector;

// Check if binaries are available
$requirements = PlatformDetector::checkRequirements(['yt-dlp', 'ffmpeg']);
foreach ($requirements as $binary => $info) {
    if ($info['exists']) {
        echo "✓ {$binary}: {$info['path']}\n";
    } else {
        echo "✗ {$binary}: Not found\n";
        echo $info['instructions'] . "\n";
    }
}

Custom Paths (Optional)

You can override default binary locations:

// Get executable path (auto-detection with Windows support)
$ytdlp = PlatformDetector::getExecutablePath('yt-dlp');

// Get executable path (custom location)
$ffmpeg = PlatformDetector::getExecutablePath('ffmpeg', '/usr/local/bin/ffmpeg');

// Platform-specific binary names are handled automatically
// Windows: yt-dlp.exe, ffmpeg.exe
// Linux/macOS: yt-dlp, ffmpeg

Documentation

Why This Library?

✅ User Control

  • No Auto-Downloads: You choose and manage your tools
  • Custom Paths: Override any binary location
  • Transparent: Know exactly what tools are being used

✅ Cross-Platform Ready

  • Platform Detection: Automatic Windows/Linux/macOS support
  • Path Normalization: Handles different path separators
  • Extension Handling: .exe on Windows, none on Unix systems

✅ Modern PHP

  • PHP 8.3+: Latest features and performance
  • Strict Types: Type safety throughout
  • Exception Handling: Specific exception types with clear error messages
  • Windows Support: Native Windows path handling and binary detection

✅ Production Ready

  • Memory Efficient: Streams large files
  • Progress Tracking: Monitor long conversions
  • Error Recovery: Graceful failure handling

Community

Get started with the Getting Started Guide →