pw-cat - Man Page

• Play a WAV file over the default target: pw-cat [-p|--playback] path/to/file.wav
• Play a MIDI file: pw-cat [-pm|--playback --midi] path/to/file.mid
• Play a DSD file: pw-cat [-pd|--playback --dsd] path/to/file.dsf
• Play a compressed audio file using passthrough (requires FFmpeg integration): pw-cat [-po|--playback --encoded] path/to/file.ac3
• Play a WAV file with a specified resampler quality (4 by default): pw-cat [-p|--playback] [-q|--quality] 0..15 path/to/file.wav
• Record a MIDI file: pw-cat [-rm|--record --midi] path/to/file.mid
• Record a sample recording at a volume level of 125%: pw-cat [-r|--record] --volume 1.25 path/to/file.wav
• Record a sample recording using a different sample rate: pw-cat [-r|--record] --rate 6000 path/to/file.wav

tldr.sh

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 | -]

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​.

-h | --help

Show help​.

--version

Show version information​.

-v | --verbose

Verbose operation​.

-R | --remote=NAME

The name the remote instance to connect to​. If left unspecified, a connection is made to the default PipeWire instance​.

-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​.

-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​.

-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​.

-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​.

-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​.

-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​.

--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​.

--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​.

--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​.

--target=VALUE

Set a node target (default auto)​. The value can be:

• auto: Automatically select (Default)
• 0: Don't try to link this node
• <id>: The object​.serial or the node​.name of a target node

--latency=VALUE[units]

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​.

-P | --properties=VALUE

Set extra stream properties as a JSON object​.

-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​.

-a | --raw

Raw samples will be read or written​. The --rate, --format, --channels and --channelmap can be used to specify the raw format​.

-M | --force-midi

Force midi format, one of "midi" or "ump", (default ump)​. When reading or writing midi, for one of midi or UMP​.

-n | --sample-count=COUNT

Stop after COUNT samples​.

--rate=VALUE

The sample rate, default 48000​.

--channels=VALUE

The number of channels, default 2​.

--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​.

--list-layouts

List all known channel layouts​. One of these can be used as the --channel-map value​.

--list-channel-names

List all known channel names​. An array of these can be used as the --channel-map value​.

--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​.

--list-formats

List all known format values​.

--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​.

--list-containers

List all known container values​.

--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​.

The PipeWire Developers <https://gitlab.freedesktop.org/pipewire/pipewire/issues>; PipeWire is available from <https://pipewire.org>

pipewire(1), pw-mon(1),