pw-cat

Play a WAV file over the default target

$ pw-cat [[-p|--playback]] [path/to/file.wav]

$ pw-cat [[-q|--quality]] [0..15] [[-p|--playback]] [path/to/file.wav]

$ pw-cat [[-r|--record]] --volume [1.25] [path/to/file.wav]

$ pw-cat [[-r|--record]] --rate [6000] [path/to/file.wav]

$ pw-cat [[-h|--help]]

pw-cat [OPTIONS] [FILENAME]
Where FILENAME can be an input file for playback or an output file for recording.

-h, --help
    Display help information and exit.

--version
    Show program version.

-p, --playback
    Enable playback mode to a PipeWire sink (default if no -r is used).

-r, --record
    Enable recording mode from a PipeWire source.

-R, --loop
    Loop playback indefinitely. (Playback mode only)

-m, --monitor
    Record from a monitor output of a source. (Recording mode only)

-v, --verbose
    Increase verbosity of output.

-P, --properties=PROPERTIES
    Set stream properties as a key=value string (e.g., "node.target=my_sink").

-l, --latency=LATENCY
    Set stream latency (e.g., "100ms", "4/48000").

-d, --driver=DRIVER
    Force a specific driver for the stream.

-q, --quality=QUALITY
    Set audio quality parameters (e.g., "rate=48000", "channels=2").

-i, --input=FILENAME
    Explicitly specify the input audio file.

-o, --output=FILENAME
    Explicitly specify the output audio file.

-s, --server=SERVER
    Connect to a specific PipeWire server.

-n, --name=NAME
    Set the client application name for PipeWire.

--raw
    Treat audio data as raw PCM (no WAV header).

--rate=RATE
    Set the sample rate in Hz (e.g., 48000). Implies --raw if no format is specified.

--channels=CHANNELS
    Set the number of audio channels (e.g., 2 for stereo). Implies --raw if no format is specified.

--format=FORMAT
    Set the sample format (e.g., s16le, f32le). Implies --raw.

--volume=VOLUME
    Set the playback/recording volume (0.0 to 1.0).

--target=TARGET
    Specify the target node (sink or source) by name.

pw-cat is a command-line utility for playing and recording audio streams through the PipeWire sound server. It operates similarly to the standard cat command, but designed for audio data. Users can specify an input FILENAME for playback or an output FILENAME for recording. If no filename is provided, pw-cat defaults to reading audio from standard input (stdin) and writing it to standard output (stdout), making it highly versatile for piping audio data between processes.

It supports various audio formats, including raw PCM and WAV files, and offers numerous options to control parameters such as sample rate, number of channels, audio format, latency, and specific target audio devices. This tool is part of the pipewire-utils package and is engineered for low-latency audio operations within the PipeWire ecosystem.

Requires a running PipeWire daemon. When using stdin/stdout for raw audio, parameters like --rate, --channels, and --format are crucial, as pw-cat cannot infer these from a WAV header. The FILENAME argument is positional and can be ambiguous without --input or --output flags if you want to explicitly define source/destination when stdin/stdout is not intended.

When no FILENAME is specified, pw-cat reads audio data from standard input (stdin) and writes it to standard output (stdout). This behavior allows it to be easily integrated into shell pipelines, processing or generating audio streams on the fly. For raw audio through stdin/stdout, it's essential to explicitly define audio parameters such as --rate, --channels, and --format.

By default, pw-cat operates in playback mode unless the -r (record) option is explicitly used. This means if a FILENAME is provided, it will play the audio from that file. If no FILENAME is given and -r is not used, it will attempt to play audio from standard input (stdin).

pw-cat is a relatively recent addition to the Linux audio landscape, emerging as part of the PipeWire project. PipeWire itself was developed to address limitations of existing audio (PulseAudio, JACK) and video (V4L2, GStreamer) infrastructures, aiming for a unified, low-latency multimedia graph. pw-cat simplifies basic audio I/O, providing a familiar cat-like interface for developers and users working with PipeWire streams, often used in scripting or for quick tests alongside other command-line tools. Its development parallels the growth and adoption of PipeWire as a modern audio and video server.

pipewire(1), pw-play(1), pw-record(1), cat(1)