.TH "pw-cat" 1 "1.6.8" "PipeWire" \" -*- nroff -*- .ad l .nh .SH NAME pw-cat \- Play and record media with PipeWire .PP .SH "SYNOPSIS" .PP .PP \fBpw-cat\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-play\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-record\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-midiplay\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-midirecord\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-midi2play\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-midi2record\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP \fBpw-dsdplay\fP [\fIoptions\fP] [\fIFILE\fP | -] .PP .SH "DESCRIPTION" .PP .PP \fBpw-cat\fP 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 \fRlibsndfile\fP 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\&. .PP 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\&. .PP 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\&. .PP When the \fIFILE\fP 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\&. .PP When the \fIFILE\fP 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\&. .PP .SH "OPTIONS" .PP .PP \fB-h | --help\fP .RS 4 Show help\&. .RE .PP \fB--version\fP .RS 4 Show version information\&. .RE .PP \fB-v | --verbose\fP .RS 4 Verbose operation\&. .RE .PP \fB-R | --remote=NAME\fP .RS 4 The name the \fIremote\fP instance to connect to\&. If left unspecified, a connection is made to the default PipeWire instance\&. .RE .PP \fB-p | --playback\fP .RS 4 Playback mode\&. Read data from the specified file, and play it back\&. If the tool is called under the name \fBpw-play\fP, \fBpw-midiplay\fP or \fBpw-midi2play\fP this is the default\&. .RE .PP \fB-r | --record\fP .RS 4 Recording mode\&. Capture data and write it to the specified file\&. If the tool is called under the name \fBpw-record\fP, \fBpw-midirecord\fP or \fBpw-midi2record\fP this is the default\&. .RE .PP \fB-m | --midi\fP .RS 4 MIDI mode\&. \fIFILE\fP is a MIDI file\&. If the tool is called under the name \fBpw-midiplay\fP or \fBpw-midirecord\fP this is the default\&. Note that this program will \fInot\fP 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\&. .RE .PP \fB-c | --midi-clip\fP .RS 4 MIDI 2\&.0 clip mode\&. \fIFILE\fP is a MIDI 2\&.0 clip file\&. If the tool is called under the name \fBpw-midi2play\fP or \fBpw-midi2record\fP this is the default\&. Note that this program will \fInot\fP 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\&. .RE .PP \fB-d | --dsd\fP .RS 4 DSD mode\&. \fIFILE\fP is a DSF file\&. If the tool is called under the name \fBpw-dsdplay\fP this is the default\&. Note that this program will \fInot\fP render the DSD audio\&. You need a DSD capable device to play DSD content or this program will exit with an error\&. .RE .PP \fB-s | --sysex\fP .RS 4 SysEx mode\&. \fIFILE\fP is a File that contains a raw SysEx MIDI message\&. If the tool is called under the name \fBpw-sysex\fP this is the default\&. The File is read and sent as a MIDI control message into the graph\&. .RE .PP \fB--media-type=VALUE\fP .RS 4 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\&. .RE .PP \fB--media-category=VALUE\fP .RS 4 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\&. .RE .PP \fB--media-role=VALUE\fP .RS 4 Set the media role property (default Music)\&. The media type is used by the session manager to select a suitable target to link to\&. .RE .PP \fB--target=VALUE\fP .RS 4 Set a node target (default auto)\&. The value can be: .PP .IP "\(bu" 2 \fBauto\fP: Automatically select (Default) .IP "\(bu" 2 \fB0\fP: Don't try to link this node .IP "\(bu" 2 \fB\fP: The object\&.serial or the node\&.name of a target node .PP .RE .PP .PP \fB--latency=VALUE[\fIunits\fP]\fP .RS 4 Set the node latency (default 100ms) .PP 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)\&. .PP 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\&. .PP Units can be \fBs\fP for seconds, \fBms\fP for milliseconds, \fBus\fP for microseconds, \fBns\fP for nanoseconds\&. If no units are given, the latency value is samples with the samplerate of the file\&. .RE .PP .PP \fB-P | --properties=VALUE\fP .RS 4 Set extra stream properties as a JSON object\&. .RE .PP \fB-q | --quality=VALUE\fP .RS 4 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\&. .RE .PP \fB-a | --raw\fP .RS 4 Raw samples will be read or written\&. The --rate, --format, --channels and --channelmap can be used to specify the raw format\&. .RE .PP \fB-M | --force-midi\fP .RS 4 Force midi format, one of "midi" or "ump", (default ump)\&. When reading or writing midi, for one of midi or UMP\&. .RE .PP \fB-n | --sample-count=COUNT\fP .RS 4 Stop after COUNT samples\&. .RE .PP \fB--rate=VALUE\fP .RS 4 The sample rate, default 48000\&. .RE .PP \fB--channels=VALUE\fP .RS 4 The number of channels, default 2\&. .RE .PP \fB--channel-map=VALUE\fP .RS 4 The channelmap\&. Possible values include are either a channel layout such as \fBmono\fP, \fBstereo\fP, \fBsurround-21\fP, \fBquad\fP, \fBsurround-22\fP, \fBsurround-40\fP, or comma separated array of channel names such as \fBFL,FR\fP\&. See --list-layouts and --list-channel-names to get a complete list of possible values\&. .RE .PP \fB--list-layouts\fP .RS 4 List all known channel layouts\&. One of these can be used as the --channel-map value\&. .RE .PP \fB--list-channel-names\fP .RS 4 List all known channel names\&. An array of these can be used as the --channel-map value\&. .RE .PP \fB--format=VALUE\fP .RS 4 The sample format to use\&. Some possible values include: \fBu8\fP, \fBs8\fP, \fBs16\fP (default), \fBs24\fP, \fBs32\fP, \fBf32\fP, \fBf64\fP\&. See --list-formats to get a complete list of values\&. .RE .PP \fB--list-formats\fP .RS 4 List all known format values\&. .RE .PP \fB--container=VALUE\fP .RS 4 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\&. .RE .PP \fB--list-containers\fP .RS 4 List all known container values\&. .RE .PP \fB--volume=VALUE\fP .RS 4 The stream volume, default 1\&.000\&. Depending on the locale you have configured, "," or "\&." may be used as a decimal separator\&. Check with \fBlocale\fP command\&. .RE .PP .SH "AUTHORS" .PP .PP The PipeWire Developers ; PipeWire is available from .PP .SH "SEE ALSO" .PP .PP \fBpipewire(1)\fP, \fBpw-mon(1)\fP,