Troubleshooting - darkwob/youtube-mp3-converter GitHub Wiki

Troubleshooting

System Requirements

PHP Version Check

Problem: PHP version incompatibility.

Required: PHP 8.3 or higher

Check your version:

php -v

Solution:

  • Update PHP to 8.4+
  • For Ubuntu/Debian: sudo apt install php8.3-cli php8.3-fpm
  • For CentOS/RHEL: sudo dnf install php83-php-cli
  • For Windows: Download from php.net
  • For macOS: brew install [email protected]

Missing Dependencies

Problem: Error message "FFmpeg binary not found" or "yt-dlp not found".

Solution:

  1. Install FFmpeg:
# Check FFmpeg installation
ffmpeg -version

# Install if missing
# Windows: Download from ffmpeg.org or use Chocolatey
choco install ffmpeg

# Linux (Ubuntu/Debian):
sudo apt update && sudo apt install ffmpeg

# Linux (CentOS/RHEL):
sudo dnf install ffmpeg

# macOS:
brew install ffmpeg
  1. Install yt-dlp:
# Check yt-dlp installation
yt-dlp --version

# Install via pip
pip install yt-dlp

# Or download binary from GitHub releases
# Windows: Place yt-dlp.exe in your bin directory
# Linux/macOS: Place yt-dlp in your bin directory and make executable
chmod +x yt-dlp
  1. Verify paths in your constructor:
$converter = new YouTubeConverter(
    '/usr/local/bin',  // Path containing ffmpeg and yt-dlp
    $outputPath,
    $tempPath,
    $progress,
    $options
);

Permission Denied

Problem: "Permission denied" errors when writing files.

Solution:

# Set correct permissions
chmod 755 downloads/
chmod 755 temp/
chmod 755 progress/

# Or for web server user (e.g., www-data)
chown www-data:www-data downloads/ temp/ progress/

Memory Limit Exceeded

Problem: PHP memory limit errors during conversion.

Solution:

  1. Increase PHP memory limit in php.ini:
memory_limit = 256M
  1. Or in your script:
ini_set('memory_limit', '256M');

Network Issues

Problem: Timeouts or connection errors.

Solution:

$options = new ConverterOptions();
$options
    ->setProxy('socks5://127.0.0.1:1080')  // If using proxy
    ->setRateLimit(500);                   // Limit download speed

// For timeout issues, try downloading smaller files first
// or check your internet connection

Dependencies

Required PHP Extensions

Ensure these PHP extensions are installed:

# Check installed extensions
php -m | grep -E "curl|json|mbstring|redis"

# Install missing extensions
# Ubuntu/Debian:
sudo apt install php8.4-curl php8.4-json php8.4-mbstring php8.4-redis

# CentOS/RHEL:
sudo dnf install php84-php-curl php84-php-json php84-php-mbstring php84-php-redis

# macOS:
brew install [email protected]
brew install [email protected]

# Windows:
# Enable extensions in php.ini
extension=curl
extension=json
extension=mbstring
extension=redis

Composer Dependencies

If you encounter dependency conflicts:

# Clear composer cache
composer clear-cache

# Update dependencies
composer update

# Install with specific versions if needed
composer require darkwob/youtube-mp3-converter

Error Messages

Common Error Messages

"Invalid URL" - Check YouTube URL format

// Valid URLs:
https://www.youtube.com/watch?v=VIDEO_ID
https://youtu.be/VIDEO_ID
https://www.youtube.com/watch?v=VIDEO_ID&t=30s

"Download failed" - Video may be:

  • Private or deleted
  • Geo-restricted
  • Age-restricted
  • Copyright protected

"Conversion failed" - Check:

  • FFmpeg installation
  • Sufficient disk space
  • File permissions
  • Audio format support

"Missing dependency" - Install:

  • FFmpeg (for audio conversion)
  • yt-dlp (for video downloading)

"Permission denied" - Fix file permissions:

chmod 755 downloads/ temp/ progress/

Debug Information

Get detailed error information:

try {
    $result = $converter->processVideo($url);
} catch (ConverterException $e) {
    echo "Error: " . $e->getMessage() . "\n";
    echo "File: " . $e->getFile() . "\n";
    echo "Line: " . $e->getLine() . "\n";
    
    // Enable error logging
    error_log("Converter error: " . $e->getMessage());
}

Windows-Specific Issues

Path Normalization Issues

Problem: Windows path separators or long paths causing errors.

Solution: The library now automatically handles Windows path normalization:

// The library handles these automatically
$windowsPath = "C:\\Users\\Username\\Documents\\downloads";
$mixedPath = "C:/Users/Username/Documents/downloads";
$longPath = "C:\\Users\\Username\\Documents\\very\\long\\path\\that\\exceeds\\windows\\260\\character\\limit\\...";

// If you encounter issues, use the DirectoryManager:
use Darkwob\YoutubeMp3Converter\Converter\Util\DirectoryManager;

$normalizedPath = DirectoryManager::normalizeWindowsPath($windowsPath);
$isValid = DirectoryManager::validateWindowsPath($windowsPath);

if (!$isValid) {
    echo "Path contains invalid characters or exceeds length limits\n";
}

Windows Permission Issues

Problem: "Access denied" errors when creating directories or files.

Solution:

  1. Run your application with administrator privileges
  2. Check folder permissions:
    • Right-click folder → Properties → Security → Edit
    • Add your user/application user with Modify permissions
  3. Use the DirectoryManager to validate permissions:
use Darkwob\YoutubeMp3Converter\Converter\Util\DirectoryManager;

$manager = new DirectoryManager('./downloads', './temp');
try {
    $manager->validateDirectoryPermissions('./downloads');
    echo "Directory permissions are valid\n";
} catch (DirectoryException $e) {
    echo "Permission issue: " . $e->getMessage() . "\n";
}

Binary Detection Issues

Problem: FFmpeg or yt-dlp not found on Windows.

Solution:

  1. Ensure binaries are in PATH or in the bin/ directory
  2. Check binary extensions (.exe)
  3. Use the ProcessManager for binary detection:
use Darkwob\YoutubeMp3Converter\Converter\Util\ProcessManager;

try {
    $manager = new ProcessManager('./bin');
    $ytdlpVersion = $manager->executeYtDlp(['--version']);
    $ffmpegVersion = $manager->executeFfmpeg(['-version']);
    
    echo "yt-dlp version: " . $ytdlpVersion . "\n";
    echo "FFmpeg version: " . $ffmpegVersion . "\n";
} catch (BinaryNotFoundException $e) {
    echo "Binary not found: " . $e->getMessage() . "\n";
    // Installation instructions included in exception message
}

FAQ

Q: Why is the conversion slow?

A: Several factors can affect conversion speed:

  • Network bandwidth
  • Server CPU load
  • Video quality/length
  • FFmpeg processing

Try optimizing with:

$options = new ConverterOptions();
$options
    ->setAudioQuality(2)          // Lower quality (faster)
    ->setRateLimit(1000);         // Increase download speed limit

Q: Can I download age-restricted videos?

A: Age-restricted videos may require authentication. The converter will attempt to download but may fail for some restricted content.

Q: What audio quality should I use?

A: Quality scale 0-9:

  • 0: Highest quality (largest file)
  • 2-3: Good balance
  • 5-6: Moderate quality (smaller file)
  • 9: Lowest quality (smallest file)

Q: How do I handle large playlists?

A: Current version focuses on single videos. For multiple videos:

$videos = ['url1', 'url2', 'url3'];
foreach ($videos as $url) {
    try {
        $result = $converter->processVideo($url);
        echo "Downloaded: " . $result->getTitle() . "\n";
    } catch (ConverterException $e) {
        echo "Failed: " . $e->getMessage() . "\n";
    }
}

Q: Can I run conversions in parallel?

A: Yes, using process forking or separate PHP processes:

// Fork multiple processes
$pids = [];
foreach ($videos as $url) {
    $pid = pcntl_fork();
    if ($pid == 0) {
        // Child process
        $converter->processVideo($url);
        exit(0);
    } else {
        $pids[] = $pid;
    }
}

// Wait for all to complete
foreach ($pids as $pid) {
    pcntl_waitpid($pid, $status);
}

Q: Redis connection issues?

A: Check Redis configuration:

// Test Redis connection
try {
    $redis = new \Redis();
    $redis->connect('127.0.0.1', 6379);
    $redis->ping();
    echo "Redis connection successful\n";
} catch (\Exception $e) {
    echo "Redis connection failed: " . $e->getMessage() . "\n";
}

// Use Predis as alternative
$predis = new \Predis\Client([
    'scheme' => 'tcp',
    'host'   => '127.0.0.1', 
    'port'   => 6379,
    'password' => null,
    'database' => 0
]);

$progress = new RedisProgress($predis, 'converter:', 3600);

Q: What file formats are supported?

A: Supported audio formats:

  • mp3 (most compatible)
  • aac (good compression)
  • wav (uncompressed)
  • m4a (Apple format)
  • opus (best compression)
  • vorbis (OGG format)
  • flac (lossless)

Q: How to handle errors gracefully?

A: Implement comprehensive error handling:

function safeConvert($converter, $url) {
    try {
        return $converter->processVideo($url);
    } catch (ConverterException $e) {
        // Log error
        error_log("Conversion failed for $url: " . $e->getMessage());
        
        // Return error info instead of throwing
        return [
            'success' => false,
            'error' => $e->getMessage(),
            'url' => $url
        ];
    }
}