diff options
Diffstat (limited to 'DOCS/man/ao.rst')
| -rw-r--r-- | DOCS/man/ao.rst | 249 |
1 files changed, 249 insertions, 0 deletions
diff --git a/DOCS/man/ao.rst b/DOCS/man/ao.rst new file mode 100644 index 0000000..4e4e454 --- /dev/null +++ b/DOCS/man/ao.rst @@ -0,0 +1,249 @@ +AUDIO OUTPUT DRIVERS +==================== + +Audio output drivers are interfaces to different audio output facilities. The +syntax is: + +``--ao=<driver1,driver2,...[,]>`` + Specify a priority list of audio output drivers to be used. + +If the list has a trailing ',', mpv will fall back on drivers not contained +in the list. + +.. note:: + + See ``--ao=help`` for a list of compiled-in audio output drivers. The + driver ``--ao=alsa`` is preferred. ``--ao=pulse`` is preferred on systems + where PulseAudio is used. On BSD systems, ``--ao=oss`` is preferred. + +Available audio output drivers are: + +``alsa`` (Linux only) + ALSA audio output driver + + See `ALSA audio output options`_ for options specific to this AO. + + .. warning:: + + To get multichannel/surround audio, use ``--audio-channels=auto``. The + default for this option is ``auto-safe``, which makes this audio output + explicitly reject multichannel output, as there is no way to detect + whether a certain channel layout is actually supported. + + You can also try `using the upmix plugin + <https://github.com/mpv-player/mpv/wiki/ALSA-Surround-Sound-and-Upmixing>`_. + This setup enables multichannel audio on the ``default`` device + with automatic upmixing with shared access, so playing stereo + and multichannel audio at the same time will work as expected. + +``oss`` + OSS audio output driver + +``jack`` + JACK (Jack Audio Connection Kit) audio output driver. + + The following global options are supported by this audio output: + + ``--jack-port=<name>`` + Connects to the ports with the given name (default: physical ports). + ``--jack-name=<client>`` + Client name that is passed to JACK (default: ``mpv``). Useful + if you want to have certain connections established automatically. + ``--jack-autostart=<yes|no>`` + Automatically start jackd if necessary (default: disabled). Note that + this tends to be unreliable and will flood stdout with server messages. + ``--jack-connect=<yes|no>`` + Automatically create connections to output ports (default: enabled). + When enabled, the maximum number of output channels will be limited to + the number of available output ports. + ``--jack-std-channel-layout=<waveext|any>`` + Select the standard channel layout (default: waveext). JACK itself has no + notion of channel layouts (i.e. assigning which speaker a given + channel is supposed to map to) - it just takes whatever the application + outputs, and reroutes it to whatever the user defines. This means the + user and the application are in charge of dealing with the channel + layout. ``waveext`` uses WAVE_FORMAT_EXTENSIBLE order, which, even + though it was defined by Microsoft, is the standard on many systems. + The value ``any`` makes JACK accept whatever comes from the audio + filter chain, regardless of channel layout and without reordering. This + mode is probably not very useful, other than for debugging or when used + with fixed setups. + +``coreaudio`` (macOS only) + Native macOS audio output driver using AudioUnits and the CoreAudio + sound server. + + Automatically redirects to ``coreaudio_exclusive`` when playing compressed + formats. + + The following global options are supported by this audio output: + + ``--coreaudio-change-physical-format=<yes|no>`` + Change the physical format to one similar to the requested audio format + (default: no). This has the advantage that multichannel audio output + will actually work. The disadvantage is that it will change the + system-wide audio settings. This is equivalent to changing the ``Format`` + setting in the ``Audio Devices`` dialog in the ``Audio MIDI Setup`` + utility. Note that this does not affect the selected speaker setup. + + ``--coreaudio-spdif-hack=<yes|no>`` + Try to pass through AC3/DTS data as PCM. This is useful for drivers + which do not report AC3 support. It converts the AC3 data to float, + and assumes the driver will do the inverse conversion, which means + a typical A/V receiver will pick it up as compressed IEC framed AC3 + stream, ignoring that it's marked as PCM. This disables normal AC3 + passthrough (even if the device reports it as supported). Use with + extreme care. + + +``coreaudio_exclusive`` (macOS only) + Native macOS audio output driver using direct device access and + exclusive mode (bypasses the sound server). + +``openal`` + OpenAL audio output driver. + + ``--openal-num-buffers=<2-128>`` + Specify the number of audio buffers to use. Lower values are better for + lower CPU usage. Default: 4. + + ``--openal-num-samples=<256-32768>`` + Specify the number of complete samples to use for each buffer. Higher + values are better for lower CPU usage. Default: 8192. + + ``--openal-direct-channels=<yes|no>`` + Enable OpenAL Soft's direct channel extension when available to avoid + tinting the sound with ambisonics or HRTF. Default: yes. + +``pulse`` + PulseAudio audio output driver + + The following global options are supported by this audio output: + + ``--pulse-host=<host>`` + Specify the host to use. An empty <host> string uses a local connection, + "localhost" uses network transfer (most likely not what you want). + + ``--pulse-buffer=<1-2000|native>`` + Set the audio buffer size in milliseconds. A higher value buffers + more data, and has a lower probability of buffer underruns. A smaller + value makes the audio stream react faster, e.g. to playback speed + changes. "native" lets the sound server determine buffers. + + ``--pulse-latency-hacks=<yes|no>`` + Enable hacks to workaround PulseAudio timing bugs (default: no). If + enabled, mpv will do elaborate latency calculations on its own. If + disabled, it will use PulseAudio automatically updated timing + information. Disabling this might help with e.g. networked audio or + some plugins, while enabling it might help in some unknown situations + (it used to be required to get good behavior on old PulseAudio versions). + + If you have stuttering video when using pulse, try to enable this + option. (Or try to update PulseAudio.) + + ``--pulse-allow-suspended=<yes|no>`` + Allow mpv to use PulseAudio even if the sink is suspended (default: no). + Can be useful if PulseAudio is running as a bridge to jack and mpv has its sink-input set to the one jack is using. + +``pipewire`` + PipeWire audio output driver + + The following global options are supported by this audio output: + + ``--pipewire-buffer=<1-2000|native>`` + Set the audio buffer size in milliseconds. A higher value buffers + more data, and has a lower probability of buffer underruns. A smaller + value makes the audio stream react faster, e.g. to playback speed + changes. "native" lets the sound server determine buffers. + + ``--pipewire-remote=<remote>`` + Specify the PipeWire remote daemon name to connect to via local UNIX + sockets. + An empty <remote> string uses the default remote named ``pipewire-0``. + + ``--pipewire-volume-mode=<channel|global>`` + Specify if the ``ao-volume`` property should apply to the channel + volumes or the global volume. + By default the channel volumes are used. + +``sdl`` + SDL 1.2+ audio output driver. Should work on any platform supported by SDL + 1.2, but may require the ``SDL_AUDIODRIVER`` environment variable to be set + appropriately for your system. + + .. note:: This driver is for compatibility with extremely foreign + environments, such as systems where none of the other drivers + are available. + + The following global options are supported by this audio output: + + ``--sdl-buflen=<length>`` + Sets the audio buffer length in seconds. Is used only as a hint by the + sound system. Playing a file with ``-v`` will show the requested and + obtained exact buffer size. A value of 0 selects the sound system + default. + +``null`` + Produces no audio output but maintains video playback speed. You can use + ``--ao=null --ao-null-untimed`` for benchmarking. + + The following global options are supported by this audio output: + + ``--ao-null-untimed`` + Do not simulate timing of a perfect audio device. This means audio + decoding will go as fast as possible, instead of timing it to the + system clock. + + ``--ao-null-buffer`` + Simulated buffer length in seconds. + + ``--ao-null-outburst`` + Simulated chunk size in samples. + + ``--ao-null-speed`` + Simulated audio playback speed as a multiplier. Usually, a real audio + device will not go exactly as fast as the system clock. It will deviate + just a little, and this option helps to simulate this. + + ``--ao-null-latency`` + Simulated device latency. This is additional to EOF. + + ``--ao-null-broken-eof`` + Simulate broken audio drivers, which always add the fixed device + latency to the reported audio playback position. + + ``--ao-null-broken-delay`` + Simulate broken audio drivers, which don't report latency correctly. + + ``--ao-null-channel-layouts`` + If not empty, this is a ``,`` separated list of channel layouts the + AO allows. This can be used to test channel layout selection. + + ``--ao-null-format`` + Force the audio output format the AO will accept. If unset accepts any. + +``pcm`` + Raw PCM/WAVE file writer audio output + + The following global options are supported by this audio output: + + ``--ao-pcm-waveheader=<yes|no>`` + Include or do not include the WAVE header (default: included). When + not included, raw PCM will be generated. + ``--ao-pcm-file=<filename>`` + Write the sound to ``<filename>`` instead of the default + ``audiodump.wav``. If ``no-waveheader`` is specified, the default is + ``audiodump.pcm``. + ``--ao-pcm-append=<yes|no>`` + Append to the file, instead of overwriting it. Always use this with the + ``no-waveheader`` option - with ``waveheader`` it's broken, because + it will write a WAVE header every time the file is opened. + +``sndio`` + Audio output to the OpenBSD sndio sound system + + (Note: only supports mono, stereo, 4.0, 5.1 and 7.1 channel + layouts.) + +``wasapi`` + Audio output to the Windows Audio Session API. |