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
}