mirror of
https://gitlab.freedesktop.org/pipewire/pipewire.git
synced 2026-02-13 04:27:51 -05:00
a2df282086
Add a container option to override the extension check and force a container when saving. Add some more formats that are supported by libsndfile. Add some options to list all supported formats, extensions/containers, layouts and channel names. Fixes #5117
217 lines
7.4 KiB
Markdown
217 lines
7.4 KiB
Markdown
\page page_man_pw-cat_1 pw-cat
|
|
|
|
Play and record media with PipeWire
|
|
|
|
# SYNOPSIS
|
|
|
|
**pw-cat** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-play** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-record** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-midiplay** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-midirecord** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-midi2play** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-midi2record** \[*options*\] \[*FILE* \| -\]
|
|
|
|
**pw-dsdplay** \[*options*\] \[*FILE* \| -\]
|
|
|
|
# DESCRIPTION
|
|
|
|
**pw-cat** is a simple tool for playing back or capturing raw or encoded
|
|
media files on a PipeWire server. It understands all audio file formats
|
|
supported by `libsndfile` for PCM capture and playback. When no container
|
|
is specified for capturing PCM, the filename extension is used to guess
|
|
the file format with the WAV file format as the default.
|
|
|
|
It understands standard MIDI files and MIDI 2.0 clip files for playback
|
|
and recording. This tool will not render MIDI files, it will simply make
|
|
the MIDI events available to the graph. You need a MIDI renderer such as
|
|
qsynth, timidity or a hardware MIDI renderer to hear the MIDI.
|
|
|
|
DSD playback is supported with the DSF file format. This tool will only
|
|
work with native DSD capable hardware and will produce an error when no
|
|
such hardware was found.
|
|
|
|
When the *FILE* is - input will be from STDIN. If no format is specified,
|
|
libsndfile will attempt to parse and stream the format from STDIN. For
|
|
some formats, this is not possible and libsndfile will give an error.
|
|
Raw, MIDI and DSD formats are all streamable from STDIN.
|
|
|
|
When the *FILE* is - output will be to STDOUT. If no format is specified,
|
|
libsndfile is instructed to output the .au format, which is streamble and
|
|
preserves the format, rate and channels.
|
|
Raw and DSD formats are all streamable to STDOUT.
|
|
|
|
# OPTIONS
|
|
|
|
\par -h | \--help
|
|
Show help.
|
|
|
|
\par \--version
|
|
Show version information.
|
|
|
|
\par -v | \--verbose
|
|
Verbose operation.
|
|
|
|
\par -R | \--remote=NAME
|
|
The name the *remote* instance to connect to. If left unspecified, a
|
|
connection is made to the default PipeWire instance.
|
|
|
|
\par -p | \--playback
|
|
Playback mode. Read data from the specified file, and play it back. If
|
|
the tool is called under the name **pw-play**, **pw-midiplay** or
|
|
**pw-midi2play** this is the default.
|
|
|
|
\par -r | \--record
|
|
Recording mode. Capture data and write it to the specified file. If the
|
|
tool is called under the name **pw-record**, **pw-midirecord** or
|
|
**pw-midi2record** this is the default.
|
|
|
|
\par -m | \--midi
|
|
MIDI mode. *FILE* is a MIDI file. If the tool is called under the name
|
|
**pw-midiplay** or **pw-midirecord** this is the default. Note that this
|
|
program will *not* render the MIDI events into audible samples, it will
|
|
simply provide the MIDI events in the graph. You need a separate MIDI
|
|
renderer such as qsynth, timidity or a hardware renderer to hear the
|
|
MIDI.
|
|
|
|
\par -c | \--midi-clip
|
|
MIDI 2.0 clip mode. *FILE* is a MIDI 2.0 clip file. If the tool is called
|
|
under the name **pw-midi2play** or **pw-midi2record** this is the default.
|
|
Note that this program will *not* render the MIDI events into audible
|
|
samples, it will simply provide the MIDI events in the graph. You need a
|
|
separate MIDI renderer such as qsynth, timidity or a hardware renderer to
|
|
hear the MIDI.
|
|
|
|
\par -d | \--dsd
|
|
DSD mode. *FILE* is a DSF file. If the tool is called under the name
|
|
**pw-dsdplay** this is the default. Note that this program will *not*
|
|
render the DSD audio. You need a DSD capable device to play DSD content
|
|
or this program will exit with an error.
|
|
|
|
\par -s | \--sysex
|
|
SysEx mode. *FILE* is a File that contains a raw SysEx MIDI message.
|
|
If the tool is called under the name **pw-sysex** this is the default.
|
|
The File is read and sent as a MIDI control message into the graph.
|
|
|
|
\par \--media-type=VALUE
|
|
Set the media type property (default Audio/Midi depending on mode). The
|
|
media type is used by the session manager to select a suitable target to
|
|
link to.
|
|
|
|
\par \--media-category=VALUE
|
|
Set the media category property (default Playback/Capture depending on
|
|
mode). The media type is used by the session manager to select a
|
|
suitable target to link to.
|
|
|
|
\par \--media-role=VALUE
|
|
Set the media role property (default Music). The media type is used by
|
|
the session manager to select a suitable target to link to.
|
|
|
|
\par \--target=VALUE
|
|
\parblock
|
|
Set a node target (default auto). The value can be:
|
|
|
|
- **auto**: Automatically select (Default)
|
|
|
|
- **0**: Don't try to link this node
|
|
|
|
- <b>\<id\></b>: The object.serial or the node.name of a target node
|
|
\endparblock
|
|
|
|
\par \--latency=VALUE\[*units*\]
|
|
\parblock
|
|
Set the node latency (default 100ms)
|
|
|
|
The latency determines the minimum amount of time it takes for a sample
|
|
to travel from application to device (playback) and from device to
|
|
application (capture).
|
|
|
|
The latency determines the size of the buffers that the application will
|
|
be able to fill. Lower latency means smaller buffers but higher
|
|
overhead. Higher latency means larger buffers and lower overhead.
|
|
|
|
Units can be **s** for seconds, **ms** for milliseconds, **us** for
|
|
microseconds, **ns** for nanoseconds. If no units are given, the latency
|
|
value is samples with the samplerate of the file.
|
|
\endparblock
|
|
|
|
\par -P | \--properties=VALUE
|
|
Set extra stream properties as a JSON object.
|
|
|
|
\par -q | \--quality=VALUE
|
|
Resampler quality. When the samplerate of the source or destination file
|
|
does not match the samplerate of the server, the data will be resampled.
|
|
Higher quality uses more CPU. Values between 0 and 15 are allowed, the
|
|
default quality is 4.
|
|
|
|
\par -a | \--raw
|
|
Raw samples will be read or written. The \--rate, \--format, \--channels
|
|
and \--channelmap can be used to specify the raw format.
|
|
|
|
\par -M | \--force-midi
|
|
Force midi format, one of "midi" or "ump", (default ump).
|
|
When reading or writing midi, for one of midi or UMP.
|
|
|
|
\par -n | \--sample-count=COUNT
|
|
Stop after COUNT samples.
|
|
|
|
\par \--rate=VALUE
|
|
The sample rate, default 48000.
|
|
|
|
\par \--channels=VALUE
|
|
The number of channels, default 2.
|
|
|
|
\par \--channel-map=VALUE
|
|
The channelmap. Possible values include are either a channel layout
|
|
such as **mono**, **stereo**,
|
|
**surround-21**, **quad**, **surround-22**, **surround-40**,
|
|
or comma separated array of channel names such as **FL,FR**.
|
|
See \--list-layouts and \--list-channel-names to get a complete
|
|
list of possible values.
|
|
|
|
\par \--list-layouts
|
|
List all known channel layouts. One of these can be used as the
|
|
\--channel-map value.
|
|
|
|
\par \--list-channel-names
|
|
List all known channel names. An array of these can be used as the
|
|
\--channel-map value.
|
|
|
|
\par \--format=VALUE
|
|
The sample format to use. Some possible values include: **u8**, **s8**,
|
|
**s16** (default), **s24**, **s32**, **f32**, **f64**. See
|
|
\--list-formats to get a complete list of values.
|
|
|
|
\par \--list-formats
|
|
List all known format values.
|
|
|
|
\par \--container=VALUE
|
|
Specify the container to use when saving. This is usually guessed from
|
|
the filename extension but can be specified explicitly. When using
|
|
STDOUT and no container is specified, the AU container will be used.
|
|
Then using a filename and the container was not specified and it could
|
|
not be derived from the filename, the WAV container is used.
|
|
|
|
\par \--list-containers
|
|
List all known container values.
|
|
|
|
\par \--volume=VALUE
|
|
The stream volume, default 1.000. Depending on the locale you have
|
|
configured, "," or "." may be used as a decimal separator. Check with
|
|
**locale** command.
|
|
|
|
# AUTHORS
|
|
|
|
The PipeWire Developers <$(PACKAGE_BUGREPORT)>;
|
|
PipeWire is available from <$(PACKAGE_URL)>
|
|
|
|
# SEE ALSO
|
|
|
|
\ref page_man_pipewire_1 "pipewire(1)",
|
|
\ref page_man_pw-mon_1 "pw-mon(1)",
|