@afkcodes/timbre-player

Classes

Class	Description
ContentUriResolver	Rewrites Android content:// URIs into fd:// URLs mpv can open, once per URI, for the life of the player.
Player	The typed audio player.
PlayerErrorException	An Error subclass carrying a PlayerError, so that typed information survives throw/await.
SourceResolverController	Owns one player's source resolver: the function itself, the in-flight de-duplication, the ahead-of-time resolution, and the answers to mpv.
VisualizerController	The lazy, reference-counted owner of one player's audio visualizer.

Interfaces

Interface	Description
AudioFilter	One entry of an mpv audio filter chain.
AudioFilterParamChange	One af-command: which labelled entry, which sub-option, its new value.
ChapterChangedEvent	Payload of the chapterChanged event.
ChapterEntry	One chapter of the current entry, as read from the chapter-list node property.
CommonMetadata	The tags a now-playing screen needs, normalised across tag formats.
CompressorOptions	AudioFilters.compressor options (ffmpeg acompressor).
ContentUriOpener	What ContentUriResolver needs from the platform. One method to open, one to close.
CrossfeedOptions	AudioFilters.crossfeed options.
DisposedError	The player (or its underlying mpv core) has already been destroyed.
DynamicNormalizerOptions	AudioFilters.dynamicNormalizer options (ffmpeg dynaudnorm).
EndFileEvent	A playlist entry stopped playing (MPV_EVENT_END_FILE).
Equalizer	The equaliser: its live state, and every operation an EQ screen performs on it.
EqualizerBand	One slider of the equaliser: the ISO octave centre it sits on, and where the user has it.
EqualizerGainRange	Inclusive slider bounds, in dB.
EqualizerOptions	AudioFilters.equalizer options.
EqualizerPreset	A named equaliser curve: one gain in dB per band of EQUALIZER_BANDS.
EqualizerPresetChainOptions	Options for equalizerPresetChain.
EqualizerSettings	Everything about an equaliser worth surviving a process death: whether it is on, the curve it is set to, and the curves the user saved.
EqualizerStorage	Where an equaliser is written. Injected, structurally typed, and never depended on — the same two-method shape as @afkcodes/timbre-media-session's MediaSessionStorage, deliberately, so an app can hand both libraries the same object.
GraphicEqualizerOptions	AudioFilters.graphicEqualizer options.
InvalidStateError	A call was made in a state that does not allow it (e.g. double initialize).
LimiterOptions	AudioFilters.limiter options (ffmpeg alimiter).
LoadFailedError	The source could not be opened at all (missing file, refused connection).
LoadOptions	Options for Player.load.
LoadPlaylistOptions	Options for Player.loadPlaylist.
LogEvent	An mpv log line (MPV_EVENT_LOG_MESSAGE).
LoopRaw	The raw loop-file / loop-playlist strings behind PlayerState.loop.
LoudnessNormalizationOptions	Options for Player.setLoudnessNormalization.
LoudnormOptions	AudioFilters.loudnorm options (ffmpeg loudnorm, EBU R128).
Milestone	A milestone that has been reached, exactly once per playthrough.
MpvClient	A thin, complete binding over one mpv_handle (one mpv_create() core).
MpvEvent	One event from the mpv event loop, already translated out of mpv_event.
NetworkError	Playback of a network source failed part-way: a premature EOF, a dropped connection, or a stream that never delivered decodable data.
NetworkReconnectOptions	FFmpeg's own HTTP reconnection, wired through mpv's stream-lavf-o.
ObservedProperty	One entry of the observation table: an mpv property name plus the MpvFormat it is observed in.
PassOptions	AudioFilters.lowpass / AudioFilters.highpass options.
PlaybackRestartEvent	Playback restarted after a seek or after loading finished (MPV_EVENT_PLAYBACK_RESTART). This is the point at which time-pos is meaningful again, so it is the primary position-anchor discontinuity.
PlayerErrorInfo	Extra facts about an error event, beyond the typed error itself.
PlayerEventMap	Discrete events, as opposed to the whole-state subscription.
PlayerOptions	Options for Player.create.
PlayerState	One immutable snapshot of everything the player knows.
PlaylistAddOptions	Options for PlaylistApi.add.
PlaylistApi	Queue manipulation, backed by mpv's own playlist (which is what makes gapless transitions gapless — the next entry is demuxed before the current one ends).
PlaylistEntry	One entry of mpv's playlist, as read from the playlist node property.
PlaylistPosition	Where we are in mpv's playlist.
PositionAnchor	The fixed point from which projectPosition extrapolates.
PositionAnchorMs	The same anchor in the units every remote surface speaks: milliseconds.
PrefetchActive	mpv is holding an opened-early next entry — the current track's end is going to be gapless. Carries what prefetchStarted carried, plus when it fired.
PrefetchIdle	No prefetch is in flight. The state usePrefetchStatus starts in, returns to at every boundary, and stays in forever on binaries without the prefetch hook (see the event's own docs for that honesty).
PrefetchStartedEvent	mpv has just started opening the next playlist entry ahead of time.
Progress	What useProgress returns.
PropertyEvent	A property observation changed (or became unavailable).
QueueChangedEvent	Payload of the queueChanged event.
RawMpvError	Anything mpv reported that this layer does not classify further.
ReducerContext	Everything the reducer needs that is not carried by the event itself.
ReplayGainOptions	Loudness normalisation from the ReplayGain tags embedded in a file.
RetryingEvent	Payload of the retrying event.
RetryOptions	Give a failed entry another go before the queue moves past it.
RnMediaContentSource	Turns an Android content:// URI into a file descriptor mpv can read.
RnMediaScreenState	Whether the device's display is currently on ("interactive"), and a notification when that changes.
ScreenStateSource	A source of truth for "can anything this app draws actually be seen".
SeekCompletedEvent	Payload of the seekCompleted event.
SeekEvent	A seek was initiated (MPV_EVENT_SEEK). Position is not yet valid.
SeekStartedEvent	Payload of the seekStarted event.
ShelfOptions	AudioFilters.bass / AudioFilters.treble options.
ShutdownEvent	The core is shutting down (MPV_EVENT_SHUTDOWN). No further events follow.
SourceOptions	Per-source options shared by Player.load, Player.loadPlaylist and PlaylistApi.add — everything that becomes a loadfile per-file option.
SourceResolutionRequest	mpv is about to open a source and does not know its concrete URL yet.
SourceResolverOptions	What SourceResolverController needs from its owner.
StartFileEvent	mpv began loading a playlist entry (MPV_EVENT_START_FILE).
TrackChangedEvent	Payload of the trackChanged event.
TrackChangeReads	The file-scoped values the Player reads once when the playlist cursor moves.
TrackEndedEvent	Payload of the trackEnded event.
UnsupportedError	The operation is not implemented by the audio core — currently only attachVideoOutput/detachVideoOutput, which the future video plugin owns.
UnsupportedFormatError	mpv could not demux/decode the source: no matching demuxer or codec.
UseEqualizerOptions	Options for useEqualizer.
UsePlayerOptions	Options for usePlayer.
UsePlayerResult	What usePlayer returns.
UseVisualizerResult	What useVisualizer returns.
VisualizerCapabilities	What the visualizer can deliver, probed from the linked libmpv rather than assumed.
VisualizerCapture	One analysed window of the audio mpv last handed to the audio device.
VisualizerDecodeState	Per-subscription state the smoothing and the auto-gain need between frames.
VisualizerFrame	One decoded frame, ready to paint.
VisualizerOptions	Tuning for VisualizerController.subscribe.
VolumeOptions	AudioFilters.volume options.

Type Aliases

Type Alias	Description
AudioChannelMode	Which channel layout the output is forced to — the typed subset of mpv's --audio-channels this library exposes.
AudioFilterOption	One key=value pair of a filter's sub-options, in the order it will be written. A tuple rather than an object because the compiled string is part of this module's contract and must be deterministic.
BiquadWidthType	How a biquad filter's width is interpreted (ffmpeg's width_type/t).
BuiltInSourceRewrite	A rewrite this library performs itself, before and after the app's resolver.
EndFileOutcome	How a playlist entry stopped, as classified from mpv's end-file event.
EqualizerPresetId	Identifier of a built-in preset.
EqualizerRestoreResult	What parseEqualizerSettings found. A typed result, never a throw: a corrupt record is an ordinary runtime condition (a half-written file, an app downgrade, a user clearing storage), and an app whose EQ screen has to try/catch its cold start will eventually not.
GaplessAudioMode	How hard mpv should try to keep the audio device open across a playlist entry change — mpv's `--gapless-audio=<no
HttpHeaders	HTTP request headers to send for one source, as a plain object.
LoopMode	Repeat behaviour, mapped onto mpv's loop-file / loop-playlist.
Metadata	A read-only view of the current entry's tag map — mpv's metadata property.
MpvClientFactory	A factory that produces a fresh, uninitialised MpvClient.
MpvEndFileReason	mpv_end_file_reason. unknown covers reason values added by future mpv releases.
MpvEventKind	Discriminator of MpvEvent.
MpvFormat	The mpv format a property is observed/read in.
MpvLogLevel	mpv_log_level minus no/none (which are never delivered as messages).
MpvPropertyValue	The value of an observed/read property, in its observed MpvFormat.
PlayerError	The typed error taxonomy of @afkcodes/timbre-player.
PlayerErrorCode	Machine-readable classification of a PlayerError.
PlayerEvent	A proper TypeScript discriminated union over the flat MpvEvent struct that crosses the Nitro boundary.
PlayerEventName	Name of a discrete event.
PlayerLogLevel	mpv log levels the core can be asked for, plus 'no' to silence logging.
PlayerStateSelector	A pure projection of PlayerState down to what a component needs.
PlayerStatus	Coarse lifecycle of a player.
PositionDiscontinuityReason	Why the playback position jumped — the two causes this library can tell apart from mpv's own events, and no more.
PrefetchStatus	What usePrefetchStatus returns: a discriminated union on active, so status.uri only exists where it means something.
QueueChangeReason	What this library knows about a QueueChangedEvent.
ReplayGainMode	Which ReplayGain tag set to honour, mapped 1:1 onto mpv's replaygain option (`--replaygain=<no
Retryable	Whether repeating the identical operation could plausibly succeed with nothing else changed.
SourceResolver	Turns the logical URI in a playlist into the concrete URL mpv should open.
Unsubscribe	Unsubscribes a listener. Safe to call more than once.
VisualizerListener	Called once per decoded frame.
VisualizerUnsubscribe	Removes a visualizer subscription. Safe to call more than once.

Variables

Variable	Description
AGC_SILENCE_DB	Band power below which VisualizerOptions.autoGain stops adapting.
AUDIO_FILTER_RUNTIME_PARAMS	The sub-options that can be changed on a running filter, per filter name.
AudioFilters	Factories for the audio filters this library ships bindings for.
BUFFERED_POSITION_STEP	How far PlayerState.bufferedPosition must move before the reducer publishes it, in seconds.
BUFFERING_PERCENT_STEP	How far PlayerState.bufferingPercent must move before the reducer publishes it, in percentage points.
CONTENT_URI_FD_LIMIT	How many descriptors one player keeps open at once.
CONTENT_URI_SCHEME	The scheme Android's storage picker, MediaStore and every SAF provider use.
DEFAULT_CACHE_SECS	Default --cache-secs, i.e. how far ahead the demuxer is allowed to read on a network stream.
DEFAULT_EQUALIZER_GAIN_RANGE_DB	Default bounds for a band slider: ±12 dB.
DEFAULT_EQUALIZER_STORAGE_KEY	Default storage key. Namespaced so it cannot collide with the app's own, and distinct from the media-session key so one engine can hold both.
DEFAULT_LOUDNESS_TARGET_LUFS	Default integrated-loudness target of Player.setLoudnessNormalization, in LUFS. See LoudnessNormalizationOptions.targetLufs for why −16 and not ffmpeg's −24.
DEFAULT_MILESTONES	Default marks: the scrobbling/mark as played set.
DEFAULT_PROGRESS_INTERVAL_MS	Default re-render period of useProgress, in milliseconds.
DEFAULT_RECONNECT_DELAY_MAX_SECONDS	Default NetworkReconnectOptions.maxDelaySeconds.
DEFAULT_RESOLVER_TIMEOUT_MS	Default resolverTimeoutMs: how long a play-time miss may hold mpv's core.
DEFAULT_RESOLVER_TTL_MS	Default resolverTtlMs: how long one resolution stays usable.
DEFAULT_RESTART_THRESHOLD_SECONDS	The default number of seconds into an entry after which PlaylistApi.previous restarts it instead of going back.
DEFAULT_RETRY_MAX_ATTEMPTS	Default RetryOptions.maxAttempts.
DEFAULT_USER_AGENT	Default HTTP User-Agent.
DEFAULT_VISUALIZER_FPS	Default frame rate requested by VisualizerController.subscribe.
EQUALIZER_BAND_COUNT	Number of bands in an EqualizerPreset.
EQUALIZER_BANDS	The ten ISO octave band centres, in Hz, low to high.
EQUALIZER_LIMITER_LABEL	mpv filter label of the tail limiter of an editable chain (EqualizerPresetChainOptions.editable).
EQUALIZER_PREAMP_LABEL	mpv filter label of the pre-amp entry of an editable chain (EqualizerPresetChainOptions.editable).
EQUALIZER_PRESET_LIST	The built-in presets in display order: Flat first, then alphabetical by name — which is the order a picker should show them in.
EQUALIZER_PRESETS	Every built-in preset, keyed by EqualizerPresetId.
EQUALIZER_SCHEMA_VERSION	Version stamped into every record and required on the way back in.
GRAPHIC_EQUALIZER_BANDS	Centre frequencies of superequalizer's 18 bands, in Hz.
HTTP_HEADER_FIELDS_OPTION	The mpv option a HttpHeaders map compiles to.
LIVE_EOF_BUDGET_RESET_SECONDS	How long a live entry must play, after a RetryOptions.retryLiveEof re-attempt, before its attempt budget starts over.
LOUDNESS_NORMALIZATION_LABEL	The mpv filter label of the managed loudness-normalization entry.
MANAGED_FILTER_LABEL_PREFIX	The label prefix this library reserves for the af entries it manages.
MPV_VOLUME_SCALE	mpv's volume property is a percentage: 100 is unattenuated output.
MpvProperty	mpv property names this library observes, as string constants so that the reducer's switch and the observation table can never drift apart.
OBSERVED_PROPERTIES	Every property the Player observes, with the format it observes it in. This is the complete set — time-pos is deliberately absent (see the position-projection contract in docs/specs/player-core.md §3).
VISUALIZER_DEFAULTS	Defaults for every VisualizerOptions field.

Functions

Function	Description
assertValidAudioFilters	Validate a whole chain before it is written.
classifyEndFile	Classify an end-file event into a natural end, a deliberate stop, a playlist redirect, or a typed failure.
clearPlayerError	Drop a settled error on request, leaving every other field alone.
compileAudioFilters	Compile a filter chain into the string mpv's af property takes.
compileHttpHeaderFields	Compile a header map into one http-header-fields option value.
createDecodeState	A fresh VisualizerDecodeState for bands bands.
createInitialState	The state of a freshly created, not-yet-loaded player.
createMpvClient	@afkcodes/timbre-player — a React Native audio player built on libmpv.
decodeVisualizerFrame	Turn one native capture into a paintable VisualizerFrame.
defineEqualizerPreset	Build a custom preset from your own band gains.
diffAudioFilterParams	Work out whether one chain can be turned into another in place.
disposedError	The disposed error this library raises for use-after-destroy().
equalizerBandLabel	mpv filter label of one band of an editable chain (EqualizerPresetChainOptions.editable) — rnmedia_eq_1000 for the 1 kHz band.
equalizerPresetChain	Turn a preset into a safe, ready-to-apply filter chain.
escapeAfParam	Escape one filter sub-option key or value the way mpv itself does.
escapeSubparam	Escape one sub-option key or value the way mpv itself does.
getContentUriOpener	The platform's content:// opener, created on first use.
getScreenStateSource	The installed ScreenStateSource, creating the native one on first use.
isContentUri	Whether uri is an Android content:// URI.
isMetadataProperty	Whether a property change means "the current entry's metadata changed".
isNetworkUri	Whether a source URI is fetched over the network.
isPositionDiscontinuity	Whether an event invalidates the position anchor badly enough that the Player should spend one synchronous time-pos read on it.
isRetryableErrno	Whether a bare MPV_ERROR_* number describes a condition that could clear on its own — the code: 'mpv' half of Retryable.
metadataByKeyProperty	The property that yields one metadata value by tag name.
metadataKeyProperty	The property that yields the key of the index-th metadata entry.
metadataValueProperty	The property that yields the value of the index-th metadata entry.
parseEqualizerSettings	Read back what serializeEqualizerSettings wrote.
peakResponseDb	The true peak of a curve's combined magnitude response, in dB.
playlistFilenameProperty	The property that yields the logical URI of the index-th playlist entry.
projectPosition	Project the current playback position from state's anchor.
reducePlayerState	The pure state reducer: (state, event, context) → state.
resolveVisualizerOptions	Resolve user options against VISUALIZER_DEFAULTS, clamping every field into a range the maths below is total over.
serializeEqualizerSettings	Turn settings into the exact string parseEqualizerSettings reads back.
setContentUriOpener	Replace the platform opener.
setScreenStateSource	Replace the display-state signal.
toCommonMetadata	Normalise a raw mpv tag map into CommonMetadata.
toPlayerError	Map anything thrown by the native MpvClient (or by this library) onto the typed PlayerError taxonomy.
toPlayerEvent	Translate one flat native MpvEvent into the PlayerEvent discriminated union.
toPlayerEvents	Translate a whole native batch, dropping malformed entries.
toVisualizerError	Map a throw from the native visualizer engine onto the typed taxonomy.
useEqualizer	A ten-band equaliser as one hook: the curve, the presets, the persistence, and the one af write that puts it on the signal.
useMilestones	Fire a callback once when playback passes 25 % / 50 % / 75 % / 90 % of an entry — the scrobbling primitive, forward-only and once per playthrough.
usePlayer	Create a Player on mount and destroy it on unmount.
usePlayerState	Subscribe to the whole player state.
usePrefetchStatus	The player's prefetchStarted signal as renderable state: active from the moment mpv opens the next entry early, cleared at the boundary that consumes it.
useProgress	A ticking view of the playback position.
useVisualizer	Subscribe a component to the player's visualizer for as long as it is mounted.
utf8Length	UTF-8 byte length. mpv's %N% prefix counts bytes, not UTF-16 code units.
withResyncedAnchor	Re-anchor the projection on an authoritative position, without touching any other field.