canberra-gtk-play

canberra-gtk-play [OPTIONS] [FILE...]

--id=NAME
    The event ID to play (e.g., "window-close", "dialog-information").

--description=NAME
    A verbose, human-readable description of the event.

--application-id=NAME
    The desktop file ID of the application playing the sound.

--application-name=NAME
    The verbose, human-readable name of the application.

--x11-display=DISPLAY
    The X11 display string of the application.

--x11-screen=SCREEN
    The X11 screen of the application.

--x11-window=WINDOW
    The X11 window ID of the application.

--x11-desktop=DESKTOP
    The X11 desktop ID of the application.

--x11-window-name=NAME
    The X11 window name.

--x11-window-class=NAME
    The X11 window class.

--x11-window-icon-name=NAME
    The X11 window icon name.

--x11-window-role=NAME
    The X11 window role.

--x11-startup-id=ID
    The X11 startup notification ID.

--media-role=NAME
    The media role (e.g., "event", "feedback", "notification", "alarm").

--event-id=NAME
    An alias for --id.

--event-description=NAME
    An alias for --description.

--channel=NAME
    The name of the channel to play the sound on.

--property=VALUE
    A generic property key-value pair. Can be specified multiple times.

--help
    Displays the help message and exits.

--version
    Displays version information and exits.

canberra-gtk-play is a command-line utility designed to play sound events conforming to the FreeDesktop.org Sound Theme Specification. It integrates with GTK+ applications, allowing them to provide contextual sound feedback. When invoked without a specific file, it plays a sound event identified by its ID or description (e.g., "window-close", "dialog-information"). If a file path is provided, it will play that specified audio file.

The strength of canberra-gtk-play lies in its ability to associate sound playback with the current GTK+ application context. This enables sound servers (like PulseAudio or PipeWire) to apply specific policies, such as routing, volume adjustments, or even muting based on the application, window, or type of event. It's a key component for desktop environments like GNOME, KDE, and XFCE to implement coherent and context-aware sound themes, enhancing user experience through auditory cues for system events, notifications, and user interactions.

• Requires a sound server (e.g., PulseAudio, PipeWire) that supports the libcanberra backend for full functionality and context-aware playback. Without it, it might fall back to simpler playback methods or fail.
• Relies on a configured FreeDesktop.org sound theme. If no theme is active or the specified event ID is not found, the command might not produce any sound.
• Primarily designed for GTK+ applications; its utility might be limited outside of desktop environments adhering to these standards.

This specification defines a standard way for desktop environments and applications to play system and event sounds. It includes naming conventions for common sound events (e.g., dialog-information, window-close) and mechanisms for themes to provide custom sounds for these events. canberra-gtk-play is a direct implementation of playing sounds according to this standard.

canberra-gtk-play doesn't play sound directly but rather interfaces with the underlying sound server (e.g., PulseAudio or PipeWire via the libcanberra library). It passes metadata (like application ID, event ID, X11 window info) to the sound server, which can then use this context to apply sophisticated routing, volume control, or effects based on user preferences or system policies.

canberra-gtk-play is part of the libcanberra project, which provides a simple, abstract interface for playing event sounds. The project was initiated around 2007-2008 to bring FreeDesktop.org Sound Theme Specification support to Linux desktops, aiming to standardize how applications play sounds, replace the aging ESD (Enlightened Sound Daemon) in some contexts, and integrate better with modern sound servers like PulseAudio. Its development was driven by the need for consistent and context-aware sound feedback in desktop environments, especially for GNOME and other GTK+-based interfaces.

aplay(1), paplay(1), pactl(1), xdg-open(1), canberra(7)