pw-cat(1)

📦
version 1.6.8 · 7 versions
, in ubuntu stonking

🌸 pw-cat(1) — bestie edition 🌸

okay so you opened the manual page for pw-cat(1) from the General Commands Manual, and honestly? you're about to have a great time. this is the whole page, nothing skipped, just with the personality it deserved. 💅

✨ NAME ✨

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

like, it's one tool that cosplays as eight. genderfluid icon behavior fr fr. 🦋

💖 DESCRIPTION 💖

pw-cat is a simple little tool for playing back or capturing raw or encoded media files on a PipeWire server. not complicated, just does the thing. it understands every audio file format that libsndfile supports for PCM capture and playback. and when you're capturing PCM and didn't specify a container? it sniffs the filename extension to guess the format, and if it can't, the WAV file format is the default. lowkey intuitive of it.

it also understands standard MIDI files and MIDI 2.0 clip files for playback and recording. but listen — this tool will not render MIDI files. it does not make sound. it just makes the MIDI events available to the graph, that's it, that's the job. you need a MIDI renderer like qsynth, timidity, or an actual hardware MIDI renderer if you want to hear any of it. 🎹

DSD playback? supported, via the DSF file format. but it will only work with native DSD capable hardware, and it will produce an error when no such hardware was found. no vibes, no hardware, no DSD. 💀

when the FILE is -, input comes from STDIN. and if no format is specified, libsndfile will attempt to parse and stream the format from STDIN. heads up though: for some formats that's just not possible and libsndfile will give an error. Raw, MIDI and DSD formats are all streamable from STDIN, so those are safe. 🫶

when the FILE is -, output goes to STDOUT. and if no format is specified, libsndfile is instructed to output the .au format, which is streamable and preserves the format, rate and channels. Raw and DSD formats are all streamable to STDOUT. iconic honestly.

👑 OPTIONS 👑

  • -h | --help — show help. your little map. 🗺️
  • --version — show version information. ✨
  • -v | --verbose — verbose operation. it will yap (affectionately). 🗣️
  • -R | --remote=NAME — the name of the remote instance to connect to. if you leave it 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. same deal as above: 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 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 the locale command. 🔊
⚠️ bestie warning: locales are out here changing your decimal separator. run locale before you blame pw-cat. it's not the tool's fault. 😭

🫶 AUTHORS 🫶

the PipeWire Developers 🌟 <https://gitlab.freedesktop.org/pipewire/pipewire/issues> — and PipeWire is available from <https://pipewire.org>

🦋 SEE ALSO 🦋

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

and that's the whole page, no cap. 💖 this was pw-cat(1) from PipeWire 1.6.8 — slay, periodt, go play something. 🎧✨👑

📦 where this page comes from