Skip to content

DOCUMENTATION.md

Latest commit

 

History

History
1526 lines (1124 loc) · 67.2 KB

DOCUMENTATION.md

File metadata and controls

1526 lines (1124 loc) · 67.2 KB

Modules

AudioEffects

Advanced audio effects including gapless playback, crossfade, and bit-perfect mode

AudioPlayer

Modular Node.js Lossless Audio Player (PortAudio + FFmpeg)

DeviceManager

Manages audio device selection and configuration

PlaylistManager

Manages playlist operations including shuffle, repeat, and navigation

StreamManager

Manages HTTP/HTTPS streaming with buffering, reconnection, and error handling

Zeaker

Node.js Lossless Audio Player (PortAudio + FFmpeg) - Modular Entry Point

AudioUtils

Audio processing and format utilities

ErrorHandler

Centralized error handling utilities for the audio player

FFmpegUtils

FFmpeg-related utilities for audio processing

Functions

getAudioStreamInfo(ffprobePath, filePath) ⇒ Promise.<{sampleRate: number, channels: number, bitDepth: number, duration: number}>

Get audio stream info (sample rate, channels, bit depth, duration) from a file using ffprobe.

AudioEffects

Advanced audio effects including gapless playback, crossfade, and bit-perfect mode

Author: zevinDev

AudioEffects.AudioEffects

AudioEffects handles advanced audio processing features. Manages gapless playback, crossfade transitions, and bit-perfect mode.

Kind: static class of AudioEffects
Author: zevinDev

audioEffects.setBitPerfect(options) ⇒ object

Enable or disable bit-perfect output mode. When enabled, disables all PCM manipulation (volume, crossfade, gapless, visualization, etc.).

Kind: instance method of AudioEffects
Returns: object - Configuration result
Throws:

  • Error If configuration fails

Author: zevinDev

Param Type Default Description
options boolean | object true Pass true to enable, false to disable, or an object: { enable: boolean, sampleRate?: number, bitDepth?: number }

audioEffects.isBitPerfectMode() ⇒ boolean

Check if bit-perfect mode is enabled.

Kind: instance method of AudioEffects
Returns: boolean - True if bit-perfect mode is enabled
Author: zevinDev

audioEffects.setCrossfadeDuration(duration)

Set the crossfade duration for crossfade transitions.

Kind: instance method of AudioEffects
Throws:

  • Error If duration is invalid or in bit-perfect mode

Author: zevinDev

Param Type Description
duration number Crossfade duration in seconds (must be >= 0)

audioEffects.setCrossfadeCurve(curve)

Set the crossfade curve for crossfade transitions.

Kind: instance method of AudioEffects
Throws:

  • Error If curve is invalid or in bit-perfect mode

Author: zevinDev

Param Type Description
curve string Crossfade curve name

audioEffects.getCrossfadeConfig() ⇒ object

Get current crossfade configuration.

Kind: instance method of AudioEffects
Returns: object - Crossfade configuration
Author: zevinDev

audioEffects.prebufferNextTrack(nextTrack, ffmpegPath, [audioFormat]) ⇒ Promise.<object>

Pre-buffer the next track's PCM data for gapless playback.

Kind: instance method of AudioEffects
Returns: Promise.<object> - Prebuffering result with buffers and control functions
Throws:

  • Error If prebuffering fails

Author: zevinDev

Param Type Description
nextTrack string Path to the next audio file
ffmpegPath string Path to ffmpeg binary
[audioFormat] object Audio format settings

audioEffects.createCrossfade(currentBuffers, nextBuffers, sampleRate, channels, [duration]) ⇒ Array.<Buffer>

Create crossfade effect between two tracks.

Kind: instance method of AudioEffects
Returns: Array.<Buffer> - Mixed PCM buffers for crossfade
Throws:

  • Error If crossfade creation fails or bit-perfect mode is enabled

Author: zevinDev

Param Type Description
currentBuffers Array.<Buffer> PCM buffers from current track
nextBuffers Array.<Buffer> PCM buffers from next track
sampleRate number Audio sample rate
channels number Number of audio channels
[duration] number Crossfade duration (uses configured duration if not specified)

audioEffects.waitForGaplessReady([timeoutMs]) ⇒ Promise.<boolean>

Wait for gapless track to be ready with timeout.

Kind: instance method of AudioEffects
Returns: Promise.<boolean> - True if ready, false if timeout
Author: zevinDev

Param Type Default Description
[timeoutMs] number 2000 Timeout in milliseconds

audioEffects.getGaplessBuffers() ⇒ Array.<Buffer> | null

Get gapless playback buffers if ready.

Kind: instance method of AudioEffects
Returns: Array.<Buffer> | null - PCM buffers or null if not ready
Author: zevinDev

audioEffects.cleanupGapless()

Clean up gapless playback resources.

Kind: instance method of AudioEffects
Author: zevinDev

audioEffects.getEffectAvailability() ⇒ object

Check if advanced effects are available (not in bit-perfect mode).

Kind: instance method of AudioEffects
Returns: object - Availability status for each effect
Author: zevinDev

audioEffects.validateEffectAvailability(effectName)

Validate if an effect can be used in current mode.

Kind: instance method of AudioEffects
Throws:

  • Error If effect is not available in current mode

Author: zevinDev

Param Type Description
effectName string Name of the effect to validate

audioEffects.getConfiguration() ⇒ object

Get current audio effects configuration.

Kind: instance method of AudioEffects
Returns: object - Complete effects configuration
Author: zevinDev

AudioPlayer

Modular Node.js Lossless Audio Player (PortAudio + FFmpeg)

Author: zevinDev

AudioPlayer.AudioPlayer

Kind: static class of AudioPlayer

audioPlayer.play(filePath, [startPosition]) ⇒ Promise.<void>

Play an audio file using FFmpeg for decoding and PortAudio for output. Uses async streaming with buffer management and robust error handling.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when playback starts.
Throws:

  • TypeError If filePath is not a string or startPosition is invalid.
  • Error If playback fails or FFmpeg/PortAudio is not available.

Author: zevinDev

Param Type Default Description
filePath string Path to the audio file to play.
[startPosition] number 0 Position in seconds to start playback from.

Example

await player.play('track.flac', 10); // Start at 10 seconds

audioPlayer.pause() ⇒ Promise.<void>

Pause playback.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when playback is paused.
Throws:

  • Error If pause fails.

Emits: AudioPlayer#event:pause
Author: zevinDev

audioPlayer.resume() ⇒ Promise.<void>

Resume playback.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when playback resumes.
Throws:

  • Error If resume fails.

Emits: AudioPlayer#event:resume
Author: zevinDev

audioPlayer.stop() ⇒ Promise.<void>

Stop playback and clean up resources.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when playback is stopped.
Throws:

  • Error If stop fails.

Emits: AudioPlayer#event:stop
Author: zevinDev

audioPlayer.seek(positionSeconds) ⇒ Promise.<void>

Seek to a specific position in the current track.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when seek is complete.
Throws:

  • Error If seeking fails or no track loaded.

Emits: AudioPlayer#event:seek
Author: zevinDev

Param Type Description
positionSeconds number Position in seconds to seek to.

audioPlayer.setVolume(level) ⇒ Promise.<void>

Set playback volume.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when volume is set.
Throws:

  • Error If setting volume fails or in bit-perfect mode.

Author: zevinDev

Param Type Description
level number Volume level between 0.0 and 1.0.

audioPlayer.getVolume() ⇒ number

Get current volume level.

Kind: instance method of AudioPlayer
Returns: number - Current volume (0.0-1.0).
Author: zevinDev

audioPlayer.getMetadata() ⇒ Promise.<Object>

Extract metadata from the current track.

Kind: instance method of AudioPlayer
Returns: Promise.<Object> - Metadata object for the current track.
Throws:

  • Error If extraction fails or no track loaded.

Author: zevinDev

audioPlayer.getDuration() ⇒ number | null

Get current track duration in seconds.

Kind: instance method of AudioPlayer
Returns: number | null - Duration in seconds, or null if unknown.
Author: zevinDev

audioPlayer.playPlaylist(playlist) ⇒ Promise.<void>

Play a playlist of audio files sequentially.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when playlist starts.
Throws:

  • Error If playlist is invalid or playback fails.

Emits: AudioPlayer#event:playlistEnd
Author: zevinDev

Param Type Description
playlist Array.<string> Array of file paths to play.

audioPlayer.skip() ⇒ Promise.<void>

Skip to the next track in the playlist.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when next track starts.
Author: zevinDev

audioPlayer.previous() ⇒ Promise.<void>

Skip to the previous track in the playlist.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when previous track starts.
Author: zevinDev

audioPlayer.stopPlaylist() ⇒ void

Stop playlist playback and current track.

Kind: instance method of AudioPlayer
Author: zevinDev

audioPlayer.setPlaylistShuffle([enable]) ⇒ void

Enable or disable shuffle mode for playlists.

Kind: instance method of AudioPlayer
Author: zevinDev

Param Type Default Description
[enable] boolean true Enable shuffle if true.

audioPlayer.setPlaylistRepeat(mode) ⇒ void

Set repeat mode for playlists.

Kind: instance method of AudioPlayer
Throws:

  • Error If invalid repeat mode.

Author: zevinDev

Param Type Default Description
mode 'off' | 'one' | 'all' off Repeat mode.

audioPlayer.playGapless(nextTrack) ⇒ Promise.<void>

Enable gapless playback for the next track.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when gapless transition is set up.
Throws:

  • Error If bit-perfect mode is enabled or no active stream.

Author: zevinDev

Param Type Description
nextTrack string Path to the next audio file.

audioPlayer.crossfadeTo(nextTrack, [duration]) ⇒ Promise.<void>

Crossfade between the current and next track.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when crossfade is complete.
Throws:

  • Error If bit-perfect mode is enabled or no active stream.

Author: zevinDev

Param Type Default Description
nextTrack string Path to the next audio file.
[duration] number 3 Crossfade duration in seconds.

audioPlayer.playStream(url, [options]) ⇒ Promise.<void>

Play from a streaming source (e.g., internet radio).

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when streaming starts.
Throws:

  • Error If streaming fails.

Author: zevinDev

Param Type Description
url string Streaming source URL.
[options] object Streaming options.

audioPlayer.setOutputDevice(deviceIndex) ⇒ Promise.<void>

Set the output device for playback.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when device is set.
Throws:

  • Error If device is not found or not output-capable.

Emits: AudioPlayer#event:deviceChange
Author: zevinDev

Param Type Description
deviceIndex number Device index to use for output.

audioPlayer.setBitPerfect(options) ⇒ Promise.<void>

Enable or disable bit-perfect output mode.

Kind: instance method of AudioPlayer
Returns: Promise.<void> - Resolves when bit-perfect mode is set.
Throws:

  • Error If currently playing and unable to restart.

Author: zevinDev

Param Type Default Description
options boolean | object true Bit-perfect options or true to enable.

audioPlayer.onVisualization(callback) ⇒ void

Attach a visualization callback for PCM data.

Kind: instance method of AudioPlayer
Author: zevinDev

Param Type Description
callback function Function to receive PCM data.

audioPlayer.setBufferSize(frames) ⇒ void

Set buffer size/latency for playback.

Kind: instance method of AudioPlayer
Author: zevinDev

Param Type Description
frames number Buffer size in frames.

audioPlayer.setCrossfadeDuration(duration) ⇒ void

Set the crossfade duration.

Kind: instance method of AudioPlayer
Emits: AudioPlayer#event:crossfadeConfigChange
Author: zevinDev

Param Type Description
duration number Duration in seconds.

audioPlayer.setCrossfadeCurve(curve) ⇒ void

Set the crossfade curve.

Kind: instance method of AudioPlayer
Emits: AudioPlayer#event:crossfadeConfigChange
Author: zevinDev

Param Type Description
curve string Curve type.

audioPlayer.getStatus() ⇒ object

Get current playback status.

Kind: instance method of AudioPlayer
Returns: object - Playback status object with isPlaying, isPaused, currentTrack, etc.
Author: zevinDev

audioPlayer.getManagers() ⇒ object

Get manager instances for advanced usage.

Kind: instance method of AudioPlayer
Returns: object - Object containing device, playlist, effects, and stream managers.
Author: zevinDev

audioPlayer.getCurrentTime() ⇒ number

Get current playback time in seconds.

Kind: instance method of AudioPlayer
Returns: number - Elapsed playback time in seconds.
Author: zevinDev

AudioPlayer.listOutputDevices() ⇒ Promise.<Array>

List available PortAudio output devices.

Kind: static method of AudioPlayer
Returns: Promise.<Array> - Array of device objects.
Author: zevinDev

AudioPlayer.testSineWave() ⇒ Promise.<void>

Test PortAudio output with a synchronous 440Hz sine wave (2 seconds). Useful for debugging C++/Electron buffer issues.

Kind: static method of AudioPlayer
Returns: Promise.<void> - Resolves when test is complete.
Author: zevinDev

DeviceManager

Manages audio device selection and configuration

Author: zevinDev

DeviceManager.DeviceManager

DeviceManager handles audio device discovery and selection. Supports robust device selection across all PortAudio device types.

Kind: static class of DeviceManager
Author: zevinDev

deviceManager._initPortAudio() ⇒ Promise.<void>

Initialize PortAudio and cache reference.

Kind: instance method of DeviceManager
Throws:

  • Error If PortAudio is not available

Author: zevinDev

deviceManager.listOutputDevices() ⇒ Promise.<Array.<{index: number, name: string, maxOutputChannels: number, defaultSampleRate: number}>>

List available PortAudio output devices.

Kind: instance method of DeviceManager
Throws:

  • Error If device listing fails

Author: zevinDev

deviceManager.setOutputDevice(deviceIndex) ⇒ Promise.<object>

Set the output device for playback.

Device selection is robust across all PortAudio device types (WASAPI, ASIO, CoreAudio, ALSA, etc.). Throws if device is not found or not output-capable (maxOutputChannels > 0).

Kind: instance method of DeviceManager
Returns: Promise.<object> - Selected device info
Throws:

  • Error If device is not found or not output-capable

Emits: DeviceManager#event:deviceChange, DeviceManager#event:deviceError
Platform: Windows: WASAPI/ASIO/DirectSound; macOS: CoreAudio; Linux: ALSA/PulseAudio/JACK
Author: zevinDev

Param Type Description
deviceIndex number Device index

deviceManager.getCurrentDevice() ⇒ object | null

Get the currently selected output device.

Kind: instance method of DeviceManager
Returns: object | null - Current output device info
Author: zevinDev

deviceManager.getDefaultDevice() ⇒ Promise.<object>

Get the default output device.

Kind: instance method of DeviceManager
Returns: Promise.<object> - Default output device info
Throws:

  • Error If no default device found

Author: zevinDev

deviceManager.findDeviceByName(deviceName, [exactMatch]) ⇒ Promise.<(object|null)>

Find device by name (partial or exact match).

Kind: instance method of DeviceManager
Returns: Promise.<(object|null)> - Found device or null
Author: zevinDev

Param Type Default Description
deviceName string Device name to search for
[exactMatch] boolean false Whether to require exact match

deviceManager.validateDeviceCapabilities(device, requirements) ⇒ object

Validate device capabilities for playback requirements.

Kind: instance method of DeviceManager
Returns: object - Validation result with capabilities and warnings
Author: zevinDev

Param Type Default Description
device object Device to validate
requirements object Playback requirements
[requirements.minChannels] number 2 Minimum required channels
[requirements.preferredSampleRate] number Preferred sample rate

deviceManager.getPortAudio() ⇒ Promise.<object>

Get PortAudio instance for use by other components.

Kind: instance method of DeviceManager
Returns: Promise.<object> - PortAudio instance
Author: zevinDev

PlaylistManager

Manages playlist operations including shuffle, repeat, and navigation

Author: zevinDev

PlaylistManager.PlaylistManager

PlaylistManager handles playlist state, navigation, and playback modes. Supports shuffle, repeat modes, and efficient playlist operations.

Kind: static class of PlaylistManager
Author: zevinDev

playlistManager.loadPlaylist(playlist)

Load a new playlist.

Kind: instance method of PlaylistManager
Throws:

  • Error If playlist is invalid

Author: zevinDev

Param Type Description
playlist Array.<string> Array of file paths

playlistManager.setPlaylistShuffle([enable])

Enable or disable shuffle mode for playlists.

Kind: instance method of PlaylistManager
Author: zevinDev

Param Type Default Description
[enable] boolean true Enable shuffle if true

playlistManager.setPlaylistRepeat(mode)

Set repeat mode for playlists.

Kind: instance method of PlaylistManager
Throws:

  • Error If invalid repeat mode

Author: zevinDev

Param Type Default Description
mode 'off' | 'one' | 'all' off Repeat mode

playlistManager.getCurrentTrack() ⇒ string | null

Get the current track from the playlist.

Kind: instance method of PlaylistManager
Returns: string | null - Current track path or null if no playlist active
Author: zevinDev

playlistManager.navigateNext() ⇒ object

Navigate to the next track in the playlist. Respects shuffle and repeat settings.

Kind: instance method of PlaylistManager
Returns: object - Navigation result
Author: zevinDev

playlistManager.navigatePrevious() ⇒ object

Navigate to the previous track in the playlist.

Kind: instance method of PlaylistManager
Returns: object - Navigation result
Author: zevinDev

playlistManager.jumpToTrack(index) ⇒ string | null

Jump to a specific track index in the playlist.

Kind: instance method of PlaylistManager
Returns: string | null - Track at the specified index
Throws:

  • Error If index is invalid

Author: zevinDev

Param Type Description
index number Track index to jump to

playlistManager.getPlaylistStatus() ⇒ object

Get playlist status and information.

Kind: instance method of PlaylistManager
Returns: object - Playlist status
Author: zevinDev

playlistManager.stopPlaylist()

Stop playlist playback and clear state.

Kind: instance method of PlaylistManager
Author: zevinDev

playlistManager.clearPlaylist()

Clear playlist without affecting current playback state.

Kind: instance method of PlaylistManager
Author: zevinDev

playlistManager.addTracks(tracks, [insertIndex])

Add tracks to the current playlist.

Kind: instance method of PlaylistManager
Author: zevinDev

Param Type Description
tracks Array.<string> Array of track paths to add
[insertIndex] number Index to insert at (appends if not specified)

playlistManager.removeTracks(indices)

Remove tracks from the playlist.

Kind: instance method of PlaylistManager
Author: zevinDev

Param Type Description
indices Array.<number> Array of indices to remove

playlistManager.isPlaylistActive() ⇒ boolean

Check if the playlist is currently active.

Kind: instance method of PlaylistManager
Returns: boolean - True if playlist is active
Author: zevinDev

playlistManager.getPlaylistCopy() ⇒ Array.<string>

Get a copy of the current playlist.

Kind: instance method of PlaylistManager
Returns: Array.<string> - Copy of the playlist
Author: zevinDev

StreamManager

Manages HTTP/HTTPS streaming with buffering, reconnection, and error handling

Author: zevinDev

StreamManager.StreamManager

StreamManager handles streaming audio from HTTP/HTTPS URLs. Provides robust buffering, error handling, reconnection, and partial playback support.

Kind: static class of StreamManager
Author: zevinDev

streamManager.playStream(url, options) ⇒ Promise.<void>

Play from a streaming source with robust error handling and reconnection.

Kind: instance method of StreamManager
Throws:

  • Error If streaming fails after all retries

Author: zevinDev

Param Type Default Description
url string Streaming source URL (http(s) or file)
options object Streaming options
options.ffmpegPath string Path to ffmpeg binary
options.portaudio object PortAudio instance
options.audioStream object Audio stream for output
options.outputDevice object Output device info
[options.bufferSize] number Buffer size for audio
[options.maxRetries] number 5 Maximum retry attempts
[options.backoffBaseMs] number 500 Base backoff time in ms
[options.bufferSizeBytes] number 128*1024 Stream buffer size in bytes
[options.visualizationCallback] function Callback for PCM data
[options.emitter] function Event emitter for events

streamManager.stopStream()

Stop the current stream.

Kind: instance method of StreamManager
Author: zevinDev

streamManager.isStreaming() ⇒ boolean

Check if currently streaming.

Kind: instance method of StreamManager
Returns: boolean - True if streaming is active
Author: zevinDev

streamManager.cleanup()

Clean up all streaming resources.

Kind: instance method of StreamManager
Author: zevinDev

Zeaker

Node.js Lossless Audio Player (PortAudio + FFmpeg) - Modular Entry Point

Author: zevinDev

AudioUtils

Audio processing and format utilities

Author: zevinDev

AudioUtils.negotiateAudioFormat(trackInfo, deviceInfo, portaudio) ⇒ object

Negotiate the optimal output format between track and device capabilities. Prefers exact match, then highest supported <= track, else lowest available.

Kind: static method of AudioUtils
Returns: object - Negotiated format and required conversions.
Throws:

  • Error If portaudio.getDeviceCapabilities is not available.

Author: zevinDev

Param Type Description
trackInfo object Track info ({ sampleRate, channels, bitDepth }).
deviceInfo object Device info ({ index }).
portaudio object PortAudio binding instance.

Example

const fmt = negotiateAudioFormat(track, device, portaudio);

AudioUtils.scalePCMVolume(buffer, volume) ⇒ Float32Array

Scale PCM float32le buffer by volume (software gain).

Kind: static method of AudioUtils
Returns: Float32Array - Scaled PCM buffer as Float32Array.
Throws:

  • TypeError If buffer is not Buffer or Float32Array.

Author: zevinDev

Param Type Description
buffer Buffer | Float32Array PCM buffer (float32le format).
volume number Volume multiplier (0.0-1.0).

Example

const scaled = scalePCMVolume(buf, 0.5);

AudioUtils.mixCrossfade(currentBuffers, nextBuffers, crossfadeFrames, channels, [curve]) ⇒ Array.<Buffer>

Mix two PCM buffer arrays for crossfade effects. Supports multiple crossfade curves: linear, logarithmic, exponential.

Kind: static method of AudioUtils
Returns: Array.<Buffer> - Mixed PCM buffers.
Author: zevinDev

Param Type Default Description
currentBuffers Array.<Buffer> PCM buffers from current track.
nextBuffers Array.<Buffer> PCM buffers from next track.
crossfadeFrames number Number of frames to crossfade.
channels number Number of audio channels.
[curve] string "'linear'" Crossfade curve type.

Example

const mixed = mixCrossfade(curBufs, nextBufs, 1024, 2, 'logarithmic');

AudioUtils.shuffleArray(arr) ⇒ Array

Fisher-Yates shuffle algorithm for arrays.

Kind: static method of AudioUtils
Returns: Array - Shuffled array (new copy).
Author: zevinDev

Param Type Description
arr Array Array to shuffle.

Example

const shuffled = shuffleArray([1,2,3]);

AudioUtils.validateCrossfadeCurve(curve) ⇒ string

Validate crossfade curve parameter.

Kind: static method of AudioUtils
Returns: string - Normalized curve name.
Throws:

  • Error If curve is invalid.

Author: zevinDev

Param Type Description
curve string Curve name to validate.

Example

const c = validateCrossfadeCurve('log');

AudioUtils.durationToFrames(durationSeconds, sampleRate) ⇒ number

Calculate the number of frames for a given duration and sample rate.

Kind: static method of AudioUtils
Returns: number - Number of frames.
Author: zevinDev

Param Type Description
durationSeconds number Duration in seconds.
sampleRate number Sample rate in Hz.

Example

const frames = durationToFrames(2.5, 44100);

AudioUtils.getFrameSize(channels, [format]) ⇒ number

Get frame size in bytes for given format.

Kind: static method of AudioUtils
Returns: number - Frame size in bytes.
Author: zevinDev

Param Type Default Description
channels number Number of channels.
[format] string "'f32le'" Audio format.

Example

const size = getFrameSize(2, 'f32le');

ErrorHandler

Centralized error handling utilities for the audio player

Author: zevinDev

ErrorHandler.handleError(error, [context], [emitter])

Centralized error handler for the module. Provides user-friendly error messages and logging capabilities.

Kind: static method of ErrorHandler
Throws:

  • Error Only rethrows if configured to do so

Author: zevinDev

Param Type Default Description
error Error The error to handle
[context] string "'Unknown'" Context where the error occurred
[emitter] function Optional event emitter to emit error events

ErrorHandler.createUserFriendlyMessage(error, context) ⇒ string

Creates user-friendly error messages for common audio player errors.

Kind: static method of ErrorHandler
Returns: string - User-friendly error message
Author: zevinDev

Param Type Description
error Error The original error
context string Context where the error occurred

ErrorHandler.validateParams(params)

Validates common audio player parameters and throws appropriate errors.

Kind: static method of ErrorHandler
Throws:

  • Error If validation fails

Author: zevinDev

Param Type Description
params object Parameters to validate
params.filePath string Audio file path
params.volume number Volume level (0.0-1.0)
params.seekPosition number Seek position in seconds
params.repeatMode string Repeat mode ('off', 'one', 'all')

FFmpegUtils

FFmpeg-related utilities for audio processing

Author: zevinDev

FFmpegUtils.locateFFmpeg() ⇒ Promise.<string>

Locate the ffmpeg binary for the current platform.

Kind: static method of FFmpegUtils
Returns: Promise.<string> - Resolves with the path to the ffmpeg binary.
Throws:

  • Error If ffmpeg binary is not found.

Author: zevinDev
Example

const ffmpegPath = await locateFFmpeg();

FFmpegUtils.locateFFprobe() ⇒ Promise.<string>

Locate the ffprobe binary for the current platform.

Kind: static method of FFmpegUtils
Returns: Promise.<string> - Resolves with the path to the ffprobe binary.
Throws:

  • Error If ffprobe binary is not found.

Author: zevinDev
Example

const ffprobePath = await locateFFprobe();

FFmpegUtils.buildFFmpegArgs(options) ⇒ Array.<string>

Build FFmpeg arguments for audio conversion/decoding.

Kind: static method of FFmpegUtils
Returns: Array.<string> - FFmpeg arguments array.
Author: zevinDev

Param Type Default Description
options object Conversion options.
options.input string Input file path or 'pipe:0' for stdin.
[options.output] string "'pipe:1'" Output destination or 'pipe:1' for stdout.
[options.sampleRate] number 44100 Target sample rate.
[options.channels] number 2 Target number of channels.
[options.format] string "'f32le'" Output format.
[options.codec] string "'pcm_f32le'" Audio codec.
[options.seekPosition] number Seek position in seconds.
[options.extra] Array.<string> Extra ffmpeg arguments.

Example

const args = buildFFmpegArgs({ input: 'track.flac', sampleRate: 48000 });

FFmpegUtils.extractMetadata(filePath, [ffmpegPath]) ⇒ Promise.<Object>

Extract metadata from an audio file using ffmpeg.

Kind: static method of FFmpegUtils
Returns: Promise.<Object> - Resolves with metadata object (title, artist, album, duration, etc.).
Throws:

  • Error If extraction fails.

Author: zevinDev

Param Type Description
filePath string Path to the audio file.
[ffmpegPath] string Path to ffmpeg binary (auto-detected if not provided).

Example

const meta = await extractMetadata('track.flac');

FFmpegUtils.getAudioInfo(filePath, [ffprobePath]) ⇒ Promise.<Object>

Get detailed audio stream information from a file.

Kind: static method of FFmpegUtils
Returns: Promise.<Object> - Resolves with audio stream info (sampleRate, channels, bitDepth, duration).
Throws:

  • Error If analysis fails.

Author: zevinDev

Param Type Description
filePath string Path to the audio file.
[ffprobePath] string Path to ffprobe binary (auto-detected if not provided).

Example

const info = await getAudioInfo('track.flac');

FFmpegUtils.createFFmpegProcess(ffmpegPath, args, [options]) ⇒ ChildProcess

Create and configure an FFmpeg process for audio conversion.

Kind: static method of FFmpegUtils
Returns: ChildProcess - Configured FFmpeg process.
Author: zevinDev

Param Type Description
ffmpegPath string Path to ffmpeg binary.
args Array.<string> FFmpeg arguments.
[options] object Spawn options.

Example

const proc = createFFmpegProcess(ffmpegPath, args);

FFmpegUtils.killFFmpegProcess(process, [signal]) ⇒ void

Kill an FFmpeg process safely.

Kind: static method of FFmpegUtils
Author: zevinDev

Param Type Default Description
process ChildProcess FFmpeg process to kill.
[signal] string "'SIGKILL'" Signal to send.

Example

killFFmpegProcess(proc);

getAudioStreamInfo(ffprobePath, filePath) ⇒ Promise.<{sampleRate: number, channels: number, bitDepth: number, duration: number}>

Get audio stream info (sample rate, channels, bit depth, duration) from a file using ffprobe.

Kind: global function
Returns: Promise.<{sampleRate: number, channels: number, bitDepth: number, duration: number}> - Resolves with audio stream info.
Throws:

  • Error If ffprobe fails or no audio stream info is found, or if JSON parsing fails.

Author: zevinDev

Param Type Description
ffprobePath string Path to ffprobe executable.
filePath string Path to audio file.

Example

const info = await getAudioStreamInfo('/usr/bin/ffprobe', 'track.flac');
// info = { sampleRate: 44100, channels: 2, bitDepth: 16, duration: 123.45 }