Getting Started - darkwob/youtube-mp3-converter GitHub Wiki

Getting Started

This guide will help you get up and running with the YouTube MP3 Converter library.

Prerequisites

System Requirements

  • PHP 8.3+ with required extensions:
    • json extension
    • exec() function enabled
    • File system write permissions

External Tools (Manual Installation Required)

The library requires two external tools that you must download and install manually:

  1. yt-dlp - YouTube video downloader
  2. FFmpeg - Audio/video processing

⚠️ Important: This library does NOT automatically download these tools. You must install them yourself for security and control.

Installation

1. Install Library via Composer

composer require darkwob/youtube-mp3-converter

2. Create Binary Directory

Create a bin/ directory in your project root:

mkdir bin

Your directory structure should look like:

your-project/
├── composer.json
├── vendor/
├── bin/           # Optional: Create this directory for manual binary placement
└── src/

3. Download Required Tools

yt-dlp Installation

Windows:

# Download yt-dlp.exe
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp.exe -o bin/yt-dlp.exe

Linux:

# Download yt-dlp
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp -o bin/yt-dlp
chmod +x bin/yt-dlp

macOS:

# Download yt-dlp for macOS
curl -L https://github.com/yt-dlp/yt-dlp/releases/latest/download/yt-dlp_macos -o bin/yt-dlp
chmod +x bin/yt-dlp

FFmpeg Installation

Windows:

  1. Download from gyan.dev
  2. Extract the zip file
  3. Copy ffmpeg.exe to your bin/ directory

Linux:

# Download static build
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
tar -xf ffmpeg-release-amd64-static.tar.xz
cp ffmpeg-*-amd64-static/ffmpeg bin/
chmod +x bin/ffmpeg

macOS:

# Option 1: Use Homebrew (if available)
brew install ffmpeg
cp $(which ffmpeg) bin/

# Option 2: Direct download
curl -L https://evermeet.cx/ffmpeg/ffmpeg-latest.zip -o ffmpeg.zip
unzip ffmpeg.zip
mv ffmpeg bin/
chmod +x bin/ffmpeg

4. Verify Installation

Check that your binaries are properly installed:

<?php

require_once 'vendor/autoload.php';

use Darkwob\YoutubeMp3Converter\Converter\Util\PlatformDetector;

// Check binary requirements (auto-detects Windows .exe extensions)
$requirements = PlatformDetector::checkRequirements(['yt-dlp', 'ffmpeg']);

foreach ($requirements as $binary => $info) {
    if ($info['exists']) {
        echo "✓ {$binary} found at: {$info['path']}\n";
    } else {
        echo "✗ {$binary} not found!\n";
        echo "Instructions:\n{$info['instructions']}\n\n";
    }
}

Expected output when everything is set up correctly:

✓ yt-dlp found at: /path/to/your/project/bin/yt-dlp
✓ ffmpeg found at: /path/to/your/project/bin/ffmpeg

Directory Structure

After completing installation, your project should have this structure:

your-project/
├── composer.json
├── composer.lock
├── vendor/
│   └── darkweb/
│       └── youtube-mp3-converter/
├── bin/
│   ├── yt-dlp(.exe)      # Platform-specific
│   └── ffmpeg(.exe)      # Platform-specific
└── src/
    └── your-code.php

Basic Configuration

Create Required Directories

<?php

// Create directories for downloads and temp files
$directories = ['downloads', 'temp', 'progress'];

foreach ($directories as $dir) {
    if (!is_dir($dir)) {
        mkdir($dir, 0755, true);
        echo "Created directory: {$dir}\n";
    }
}

Test Basic Functionality

<?php

require_once 'vendor/autoload.php';

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

try {
    // Create converter instance (binaries auto-detected)
    $converter = new YouTubeConverter(
        outputPath: './downloads',
        tempPath: './temp',
        progress: new FileProgress('./progress')
    );
    
    echo "✓ YouTubeConverter created successfully!\n";
    echo "✓ All binaries found and ready to use.\n";
    
} catch (\Exception $e) {
    echo "✗ Setup error: " . $e->getMessage() . "\n";
}

Custom Binary Paths (Optional)

If you prefer to install binaries in different locations, you can use custom paths:

<?php

use Darkwob\YoutubeMp3Converter\Converter\Util\PlatformDetector;

// Test custom paths (Windows paths automatically normalized)
try {
    // Custom yt-dlp location (Windows: adds .exe automatically)
    $ytdlp = PlatformDetector::getExecutablePath('yt-dlp', '/usr/local/bin/yt-dlp');
    echo "Custom yt-dlp: {$ytdlp}\n";
    
    // Custom ffmpeg location (cross-platform path handling)
    $ffmpeg = PlatformDetector::getExecutablePath('ffmpeg', 'C:\\ffmpeg\\bin\\ffmpeg');
    echo "Custom ffmpeg: {$ffmpeg}\n";
    
} catch (\RuntimeException $e) {
    echo "Custom path error: " . $e->getMessage() . "\n";
}

Troubleshooting Installation

Common Issues

1. Permission Denied (Linux/macOS)

chmod +x bin/yt-dlp
chmod +x bin/ffmpeg

2. Command Not Found

  • Verify files are in the correct bin/ directory
  • Check file names match platform expectations
  • Ensure files are executable

3. Path Issues

  • Use forward slashes / or DIRECTORY_SEPARATOR in paths
  • Avoid spaces in directory names
  • Use absolute paths when in doubt

Verification Commands

Test binaries manually:

yt-dlp:

# Windows
bin\yt-dlp.exe --version

# Linux/macOS  
./bin/yt-dlp --version

FFmpeg:

# Windows
bin\ffmpeg.exe -version

# Linux/macOS
./bin/ffmpeg -version

Next Steps

Once installation is complete:

  1. Basic Usage - Learn simple conversion
  2. Advanced Configuration - Customize settings
  3. Examples - See real-world usage
  4. API Reference - Complete method documentation

Platform-Specific Notes

Windows

  • Use .exe extensions for executables (handled automatically by the library)
  • Path separators: \ (normalized automatically)
  • May need to exclude from antivirus scanning
  • Check Windows permissions for directory access
  • Ensure PATH environment variable includes binary locations
  • Windows path length limitations (260 characters) are handled automatically
  • Invalid Windows path characters are detected and reported

Linux

  • Ensure execute permissions: chmod +x
  • Path separators: /
  • May need to install additional dependencies

macOS

  • Ensure execute permissions: chmod +x
  • May need to allow unsigned binaries in Security preferences
  • Use Homebrew for easier installation when possible

Ready to start converting? Check out Basic Usage →