Skip to main content

Type Alias: GaplessAudioMode

type GaplessAudioMode = "no" | "yes" | "weak";

Defined in: packages/player/src/player.ts:216

How hard mpv should try to keep the audio device open across a playlist entry change — mpv's --gapless-audio=<no|yes|weak>.

This is the output side of gapless playback (the demuxer side is PlayerOptions.prefetchPlaylist). Quoting mpv 0.41.0 options.rst:

  • 'no' — "Disable gapless audio." The AO is torn down and reopened between entries, so every transition costs whatever the platform charges for a new audio device.
  • 'yes' — "The audio device is opened using parameters chosen for the first file played and is then kept open for gapless playback. This means that if the first file for example has a low sample rate, then the following files may get resampled to the same low sample rate, resulting in reduced sound quality."
  • 'weak' — mpv's default, and this library's. "Normally, the audio device is kept open (using the format it was first initialized with). If the audio format the decoder output changes, the audio device is closed and reopened. This means that you will normally get gapless audio with files that were encoded using the same settings, but might not be gapless in other cases. The exact conditions under which the audio device is kept open is an implementation detail, and can change from version to version."

Remarks​

Why this library does not force 'yes'. 'yes' buys gapless across a format change by resampling every later entry into the first entry's output format — so one 22.05 kHz interlude at the head of a queue silently degrades the whole rest of it, with no error and nothing in the state to see it by. An album (one encoder, one format) is gapless under 'weak' anyway; a mixed queue is the case where 'yes' trades audible quality for an inaudible gap. If you want 'yes', pin the shared output format too — mpv's own advice: "consider using options such as --audio-samplerate and --audio-format to explicitly select what the shared output format will be" (pass them through PlayerOptions.mpvOptions).

Note also mpv's caveat, which is why PlayerOptions.prefetchPlaylist exists alongside this: gapless "relies on audio output device buffering to continue playback while moving from one file to another. If playback of the new file starts slowly, for example because it is played from a remote network location […] then the buffered audio may run out before playback of the new file can start."