Zeaker

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


Zeaker is a high-fidelity, cross-platform audio player for Node.js, supporting gapless playback, bit-perfect output, advanced playlist management, and robust device selection. Powered by native PortAudio bindings and FFmpeg, Zeaker delivers uncompromising lossless audio playback for desktop and server environments.

---

Features

- Lossless audio playback (WAV, FLAC, ALAC, AIFF, etc.)
- Gapless playback and crossfade transitions
- Bit-perfect mode for audiophile output
- Advanced playlist management (shuffle, repeat, navigation)
- Device selection (WASAPI, ASIO, CoreAudio, ALSA, etc.)
- Streaming support (HTTP/HTTPS)
- Volume control, seeking, and metadata extraction
- Robust error handling and event-driven API

---

Installation

``sh
npm i zeaker
`

- Requires Node.js 16+
- FFmpeg and PortAudio are bundled for major platforms (Windows, macOS, Linux)

---

Usage

$3

`js
import { AudioPlayer } from "zeaker";

const player = new AudioPlayer();
player.on("play", (track) => console.log("Now playing:", track));
player.on("error", (err) => console.error("Playback error:", err));

await player.play("track.flac");
`

$3

`js
const playlist = ["song1.flac", "song2.wav", "song3.aac"];
await player.playPlaylist(playlist);
`

$3

`js
const devices = await AudioPlayer.listOutputDevices();
console.log(devices);
await player.setOutputDevice(devices[0].index); // Select first output device
`

$3

`js
await player.playStream("https://example.com/stream.mp3");
`

$3

`js
// Enable gapless playback for next track
await player.playGapless("nextTrack.flac");

// Crossfade to next track (3s duration)
await player.crossfadeTo("nextTrack.flac", 3);
`

$3

`js
player.getManagers().effects.setBitPerfect(true); // Enable bit-perfect output
player.getManagers().effects.setCrossfadeDuration(5); // 5s crossfade
`

$3

`js
await player.setVolume(0.5); // 50% volume
await player.pause();
await player.resume();
await player.seek(60); // Seek to 1:00
`

$3

`js
const metadata = await player.getMetadata();
console.log(metadata); // { title, artist, album, duration, ... }
`

---

Supported Formats

- WAV, FLAC, ALAC, AIFF, MP3, AAC, M4A, OGG, MP4, and more (via FFmpeg)

---

Error Handling

Zeaker provides robust error handling and user-friendly messages. Listen for the error event on the player instance, or use the exported handleError utility for custom handling.

---

API Reference

Zeaker exposes a modular, event-driven API. Below is a summary of the main modules and their key methods. For full details, see the source JSDoc or DOCUMENTATION.md.

$3

- AudioPlayer — Main playback API (play, pause, resume, stop, seek, volume, metadata, playlist, gapless, crossfade, streaming, device selection)
- DeviceManager — Audio device discovery, selection, and validation
- PlaylistManager — Playlist operations (load, shuffle, repeat, navigation)
- AudioEffects — Advanced effects: gapless, crossfade, bit-perfect mode
- StreamManager — HTTP/HTTPS streaming with buffering and reconnection
- AudioUtils — Audio processing and format utilities
- ErrorHandler — Centralized error handling utilities
- FFmpegUtils — FFmpeg-related utilities for audio processing

$3

#### AudioPlayer
- play(filePath, [startPosition]) — Play an audio file
- pause() / resume() / stop() — Playback controls
- seek(positionSeconds) — Seek within track
- setVolume(level) / getVolume() — Volume control
- getMetadata() — Extract metadata from current track
- getDuration() — Get track duration
- playPlaylist(playlist) — Play a playlist
- skip() / previous() — Playlist navigation
- setPlaylistShuffle([enable]) — Shuffle mode
- setPlaylistRepeat(mode) — Repeat mode
- playGapless(nextTrack) — Enable gapless playback
- crossfadeTo(nextTrack, [duration]) — Crossfade to next track
- playStream(url, [options]) — Play from streaming source
- setOutputDevice(deviceIndex) — Select output device
- setBitPerfect(options) — Enable/disable bit-perfect mode
- onVisualization(callback) — PCM visualization
- setBufferSize(frames) — Set buffer size
- setCrossfadeDuration(duration) / setCrossfadeCurve(curve) — Crossfade config
- getStatus() — Playback status
- getManagers() — Access advanced managers
- getCurrentTime() — Elapsed playback time
- listOutputDevices() (static) — List output devices
- testSineWave() (static) — Test output with sine wave

#### DeviceManager
- listOutputDevices() — List available output devices
- setOutputDevice(deviceIndex) — Select output device
- getCurrentDevice() — Get current device
- getDefaultDevice() — Get default device
- findDeviceByName(deviceName, [exactMatch]) — Find device by name
- validateDeviceCapabilities(device, requirements) — Validate device for playback

#### PlaylistManager
- loadPlaylist(playlist) — Load a new playlist
- setPlaylistShuffle([enable]) — Shuffle mode
- setPlaylistRepeat(mode) — Repeat mode
- getPlaylistCopy() — Get a copy of the playlist

#### AudioEffects
- setBitPerfect(options) — Enable/disable bit-perfect mode
- isBitPerfectMode() — Check bit-perfect status
- setCrossfadeDuration(duration) / setCrossfadeCurve(curve) — Crossfade config
- getCrossfadeConfig() — Get crossfade config
- prebufferNextTrack(nextTrack, ffmpegPath, [audioFormat]) — Pre-buffer for gapless
- createCrossfade(currentBuffers, nextBuffers, sampleRate, channels, [duration]) — Create crossfade effect
- waitForGaplessReady([timeoutMs]) — Wait for gapless ready
- getGaplessBuffers() — Get gapless buffers
- cleanupGapless() — Clean up gapless resources
- getEffectAvailability() — Check effect availability
- validateEffectAvailability(effectName) — Validate effect usage
- getConfiguration()` — Get effects config

#### StreamManager, AudioUtils, ErrorHandler, FFmpegUtils
- See DOCUMENTATION.md for details on streaming, audio utilities, error handling, and FFmpeg helpers.

---

Contributing

Pull requests and issues are welcome! Please see CONTRIBUTING.md for guidelines.

---

License

MIT © zevinDev

---