API Reference - darkwob/youtube-mp3-converter GitHub Wiki

Getting Started

// ... existing code ...

API Reference

YouTubeConverter Class

Main class for handling video conversions.

namespace Darkwob\YoutubeMp3Converter\Converter;

class YouTubeConverter implements ConverterInterface
{
    /**
     * Constructor with intelligent binary detection
     * @param string $outputPath    Path to output directory
     * @param string $tempPath      Path to temporary directory
     * @param ProgressInterface $progress Progress tracker instance
     * @param ConverterOptions|null $options Converter options (optional)
     * @param string|null $binPath  Path to binary directory (optional, auto-detected)
     */
    public function __construct(
        string $outputPath,
        string $tempPath,
        ProgressInterface $progress,
        ?ConverterOptions $options = null,
        ?string $binPath = null
    );

    /**
     * Process a single video
     * @param string $url           YouTube video URL
     * @return ConversionResult     Result object with video information
     * @throws ConverterException
     */
    public function processVideo(string $url): ConversionResult;

    /**
     * Get video information without downloading
     * @param string $url           YouTube video URL
     * @return array                Video metadata
     * @throws ConverterException
     */
    public function getVideoInfo(string $url): array;

    /**
     * Download video (internal method)
     * @param string $url           YouTube video URL
     * @param string $id            Unique process ID
     * @return string               Downloaded file path
     * @throws ConverterException
     */
    public function downloadVideo(string $url, string $id): string;
}

ConversionResult Class

Result object returned by processVideo method.

namespace Darkwob\YoutubeMp3Converter\Converter;

readonly class ConversionResult
{
    public function __construct(
        public string $outputPath,  // Full file path
        public string $title,       // Video title
        public string $videoId,     // Internal process ID
        public string $format,      // Audio format (mp3, aac, etc.)
        public int $size,          // File size in bytes
        public float $duration     // Duration in seconds
    ) {}

    /**
     * Get the output file path
     */
    public function getOutputPath(): string;

    /**
     * Get the video title
     */
    public function getTitle(): string;

    /**
     * Get the video ID
     */
    public function getVideoId(): string;

    /**
     * Get the audio format
     */
    public function getFormat(): string;

    /**
     * Get the file size in bytes
     */
    public function getSize(): int;

    /**
     * Get the duration in seconds
     */
    public function getDuration(): float;

    /**
     * Convert to array representation
     */
    public function toArray(): array;

    /**
     * Create from array data
     */
    public static function fromArray(array $data): self;
}

ConverterOptions Class

Configuration options for conversion process.

namespace Darkwob\YoutubeMp3Converter\Converter\Options;

class ConverterOptions
{
    /**
     * Set audio format
     * @param string $format        Format: mp3, aac, wav, m4a, opus, vorbis, flac
     * @return self
     * @throws ConverterException   If format is not supported
     */
    public function setAudioFormat(string $format): self;

    /**
     * Set audio quality
     * @param int $quality          Quality level 0-9 (0 = highest quality)
     * @return self
     * @throws ConverterException   If quality is not in valid range
     */
    public function setAudioQuality(int $quality): self;

    /**
     * Set custom metadata
     * @param array $metadata       Metadata array ['artist' => 'Name', 'album' => 'Album']
     * @return self
     */
    public function setMetadata(array $metadata): self;

    /**
     * Enable/disable thumbnail embedding
     * @param bool $enable          Whether to embed thumbnail as album art
     * @return self
     */
    public function enableThumbnail(bool $enable = true): self;

    /**
     * Set playlist items to process
     * @param string $items         Item selection (e.g., '1,3,5-7')
     * @return self
     */
    public function setPlaylistItems(string $items): self;

    /**
     * Set date filter (after)
     * @param string $date          Date in YYYYMMDD format
     * @return self
     */
    public function setDateAfter(string $date): self;

    /**
     * Set date filter (before)
     * @param string $date          Date in YYYYMMDD format
     * @return self
     */
    public function setDateBefore(string $date): self;

    /**
     * Set file size limit
     * @param string $limit         Size limit (e.g., '50M', '100M', '1G')
     * @return self
     */
    public function setFileSizeLimit(string $limit): self;

    /**
     * Set output template
     * @param string $template      Template string (e.g., '%(title)s.%(ext)s')
     * @return self
     */
    public function setOutputTemplate(string $template): self;

    /**
     * Set proxy
     * @param string $proxy         Proxy URL (e.g., 'socks5://127.0.0.1:1080')
     * @return self
     */
    public function setProxy(string $proxy): self;

    /**
     * Set rate limit
     * @param int $limit            Download speed limit in KB/s
     * @return self
     */
    public function setRateLimit(int $limit): self;

    // Getter methods
    public function getAudioFormat(): string;
    public function getAudioQuality(): int;
    public function getMetadata(): array;
    public function shouldEmbedThumbnail(): bool;
    public function hasMetadata(): bool;
    public function getPlaylistItems(): ?string;
    public function getDateAfter(): ?string;
    public function getDateBefore(): ?string;
    public function getFileSizeLimit(): ?string;
    public function getOutputTemplate(): ?string;
    public function getProxy(): ?string;
    public function getRateLimit(): ?int;
    public function toArray(): array;
}

Progress Tracking

FileProgress Class

File-based progress tracking implementation.

namespace Darkwob\YoutubeMp3Converter\Progress;

class FileProgress implements ProgressInterface
{
    /**
     * Constructor
     * @param string $progressDir   Directory to store progress files
     */
    public function __construct(string $progressDir);

    /**
     * Update progress
     * @param string $id            Process ID
     * @param string $status        Status (starting, downloading, converting, completed, error)
     * @param float $progress       Progress percentage (0.0 - 100.0)
     * @param string $message       Status message
     */
    public function update(string $id, string $status, float $progress, string $message): void;

    /**
     * Get current progress
     * @param string $id            Process ID
     * @return array|null           Progress data or null if not found
     */
    public function get(string $id): ?array;

    /**
     * Remove progress record
     * @param string $id            Process ID
     */
    public function remove(string $id): void;
}

RedisProgress Class

Redis-based progress tracking implementation.

namespace Darkwob\YoutubeMp3Converter\Progress;

class RedisProgress implements ProgressInterface
{
    /**
     * Constructor
     * @param \Redis|\Predis\Client $redis   Redis client instance
     * @param string $prefix                 Key prefix for Redis storage
     * @param int $defaultTtl               Default TTL for progress records
     */
    public function __construct(
        $redis,
        string $prefix = 'progress:',
        int $defaultTtl = 3600
    );

    // Same methods as FileProgress
    public function update(string $id, string $status, float $progress, string $message): void;
    public function get(string $id): ?array;
    public function remove(string $id): void;
}

DirectoryManager Class

Handles directory operations with Windows compatibility.

namespace Darkwob\YoutubeMp3Converter\Converter\Util;

class DirectoryManager
{
    /**
     * Constructor
     * @param string $outputPath    Output directory path
     * @param string $tempPath      Temporary directory path
     */
    public function __construct(string $outputPath, string $tempPath);

    /**
     * Ensure directories exist and are writable
     * @throws DirectoryException   If directories cannot be created or accessed
     */
    public function ensureDirectoriesExist(): void;

    /**
     * Create temporary directory with unique name
     * @param string $prefix        Prefix for temp directory name
     * @return string               Path to created temp directory
     * @throws DirectoryException   If directory cannot be created
     */
    public function createTempDirectory(string $prefix = 'ytdl_'): string;

    /**
     * Clean up temporary files
     * @param string $path          Path to clean up
     * @return bool                 True if cleanup was successful
     */
    public function cleanupTempFiles(string $path): bool;

    /**
     * Validate directory permissions
     * @param string $directory     Directory to validate
     * @throws DirectoryException   If directory permissions are insufficient
     */
    public function validateDirectoryPermissions(string $directory): void;

    /**
     * Normalize Windows path
     * @param string $path          Path to normalize
     * @return string               Normalized path
     */
    public static function normalizeWindowsPath(string $path): string;

    /**
     * Validate Windows path
     * @param string $path          Path to validate
     * @return bool                 True if path is valid
     */
    public static function validateWindowsPath(string $path): bool;
}

ProcessManager Class

Handles process execution with Windows compatibility.

namespace Darkwob\YoutubeMp3Converter\Converter\Util;

class ProcessManager
{
    /**
     * Constructor
     * @param string $binPath       Path to binary directory
     */
    public function __construct(string $binPath);

    /**
     * Execute yt-dlp command
     * @param array $arguments      Command arguments
     * @param string|null $workingDir Working directory
     * @return string               Command output
     * @throws ProcessException     If process execution fails
     */
    public function executeYtDlp(array $arguments, ?string $workingDir = null): string;

    /**
     * Execute FFmpeg command
     * @param array $arguments      Command arguments
     * @param string|null $workingDir Working directory
     * @param int $timeout          Process timeout in seconds
     * @return string               Command output
     * @throws ProcessException     If process execution fails
     */
    public function executeFfmpeg(array $arguments, ?string $workingDir = null, int $timeout = 3600): string;

    /**
     * Get video information
     * @param string $url           YouTube URL
     * @return array                Video metadata
     * @throws ProcessException     If process execution fails
     */
    public function getVideoInfo(string $url): array;

    /**
     * Setup Windows environment
     * @return array                Environment variables
     */
    private function setupWindowsEnvironment(): array;

    /**
     * Handle process result
     * @param Process $process      Symfony Process instance
     * @param string $command       Command being executed
     * @return string               Process output
     * @throws ProcessException     If process execution fails
     */
    private function handleProcessResult(Process $process, string $command): string;
}

PlatformDetector Class

Utility for platform detection and binary management.

namespace Darkwob\YoutubeMp3Converter\Converter\Util;

class PlatformDetector
{
    /**
     * Check if running on Windows
     * @return bool                 True if running on Windows
     */
    public static function isWindows(): bool;

    /**
     * Get executable path
     * @param string $binary        Binary name (without extension)
     * @param string|null $customPath Custom path to binary
     * @return string               Full path to executable
     * @throws BinaryNotFoundException If binary not found
     */
    public static function getExecutablePath(string $binary, ?string $customPath = null): string;

    /**
     * Check requirements
     * @param array $binaries       List of required binaries
     * @param string|null $binPath  Custom binary path
     * @return array                Status of each binary
     */
    public static function checkRequirements(array $binaries, ?string $binPath = null): array;
}

Exception Classes

ConverterException

Main exception class with specific exception types.

namespace Darkwob\YoutubeMp3Converter\Converter\Exceptions;

class ConverterException extends \Exception
{
    // Base exception class
}

class InvalidUrlException extends ConverterException
{
    // URL validation failures
}

class BinaryNotFoundException extends ConverterException
{
    // Missing binary executables
}

class DirectoryException extends ConverterException
{
    // Directory creation and permission issues
}

class ProcessException extends ConverterException
{
    // Binary execution failures
}

class NetworkException extends ConverterException
{
    // Network connection and timeout issues
}

RemoteConverter Class

Remote server-based conversion.

namespace Darkwob\YoutubeMp3Converter\Converter\Remote;

class RemoteConverter implements ConverterInterface
{
    /**
     * Constructor
     * @param string $serverUrl             Remote server URL
     * @param string $authToken             Authentication token
     * @param ProgressInterface $progress   Progress tracker
     * @param array $options               Additional options
     * @param int $timeout                 Request timeout (default: 3600)
     * @param int $connectTimeout          Connection timeout (default: 10)
     */
    public function __construct(
        string $serverUrl,
        string $authToken,
        ProgressInterface $progress,
        array $options = [],
        int $timeout = 3600,
        int $connectTimeout = 10
    );

    /**
     * Process video on remote server
     * @param string $url           YouTube video URL
     * @return ConversionResult     Result object
     * @throws ConverterException
     */
    public function processVideo(string $url): ConversionResult;

    /**
     * Get video information from remote server
     * @param string $url           YouTube video URL
     * @return array                Video metadata
     * @throws ConverterException
     */
    public function getVideoInfo(string $url): array;

    /**
     * Download video from remote server
     * @param string $url           YouTube video URL
     * @param string $id            Process ID
     * @return string               Downloaded file path
     * @throws ConverterException
     */
    public function downloadVideo(string $url, string $id): string;
}

Exception Classes

ConverterException

Main exception class with static factory methods.

namespace Darkwob\YoutubeMp3Converter\Converter\Exceptions;

class ConverterException extends \Exception
{
    // Static factory methods
    public static function invalidUrl(string $url): self;
    public static function downloadFailed(string $url, string $reason): self;
    public static function conversionFailed(string $file, string $reason): self;
    public static function fileNotFound(string $path): self;
    public static function invalidFormat(string $format): self;
    public static function invalidQuality(int $quality): self;
    public static function missingDependency(string $dependency): self;
    public static function videoInfoFailed(string $reason = ''): self;
    public static function networkError(string $url, string $reason): self;
    public static function remoteServerError(string $url, string $reason): self;
    // ... more exception types
}

ProgressException

Progress tracking specific exceptions.

namespace Darkwob\YoutubeMp3Converter\Progress\Exceptions;

class ProgressException extends \Exception
{
    // Progress-specific error handling
}