\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)",
