The canberra module

Convenience definitions

canberra.play(props: Dict[Union[str, canberra.constants.Props], str] = None, **other_props: str) → canberra._canberra.Context

Play a sound with the specified props

Parameters
  • props – A mapping of Props to values.

  • other_propsProps may also be passed as kwargs, where {Props.EVENT_ID: 'bell'} is passed as event_id='bell'.

Returns

The canberra.Context used to play the sound. cancel() may be called on this context to stop the playing sound.

canberra.play_file(filename: Union[str, pathlib.Path], **other_props: str) → canberra._canberra.Context

Play the specified sound file

Parameters
  • filename – Path to the sound file to be played

  • other_propsProps passed as kwargs, where {Props.EVENT_ID: 'bell'} is passed as event_id='bell'.

Returns

The canberra.Context used to play the sound. cancel() may be called on this context to stop the playing sound.

The Context class

class canberra.Context

A libcanberra ca_context

__init__(props: Dict[Union[str, canberra.constants.Props], str] = None, **other_props: str)

Initialize the libcanberra ca_context, optionally with default props all sounds will share

Parameters
  • props – A mapping of Props to values. These properties and values will be set as defaults for all sounds played from this context.

  • other_props – Props may also be passed as kwargs, where {Props.EVENT_ID: 'bell'} may be passed as event_id='bell'. These properties and values will be set as defaults for all sounds played from this context.

set_driver(self, driver: Union[str, bytes]) → None

Specify the backend driver used

This method may not be called again after a successful call to open(), which occurs implicitly when calling play().

This method might succeed even when the specified driver backend is not available. Use open() to find out whether the backend is available.

Parameters

driver – The backend driver to use (e.g. "alsa", "pulse", "null", …)

change_device(self, device: Union[str, bytes]) → None

Specify the backend device to use

This method may not be called again after a successful call to open(), which occurs implicitly when calling play().

This method might succeed even when the specified driver backend is not available. Use open() to find out whether the backend is available.

Depending on the backend used, this might or might not cause all currently playing event sounds to be moved to the new device.

Parameters

device – The backend device to use, in a format that is specific to the backend

open(self) → None

Connect the context to the sound system.

This is implicitly called in play() or cache() if not called explicitly. It is recommended to initialize application properties with change_props() (or when creating Context) before calling this function.

change_props(self, props: Dict[Union[str, canberra.constants.Props], str] = None, **other_props: str) → None

Write one or more string properties to the Context

Properties set like this will be attached to both the client object of the sound server and to all event sounds played or cached. It is recommended to call this method at least once before calling open() (which occurs implicitly when calling play()), so that the initial application properties are set properly before the initial connection to the sound system.

This method can be called both before and after the open() call. Properties that have already been set before will be overwritten.

Parameters
  • props – A mapping of Props to values.

  • other_propsProps may also be passed as kwargs, where {Props.EVENT_ID: 'bell'} is passed as event_id='bell'.

cache(self, props: Dict[Union[str, canberra.constants.Props], str] = None, **other_props: str) → None

Upload the specified sample into the audio server and attach the specified properties to it

This method will only return after the sample upload was finished.

The sound to cache is found with the same algorithm that is used to find the sounds for play().

If the backend doesn’t support caching sound samples, this method will raise a CanberraError with a code of NOTSUPPORTED.

Parameters
  • props – A mapping of Props to values.

  • other_propsProps may also be passed as kwargs, where {Props.EVENT_ID: 'bell'} is passed as event_id='bell'.

play(self, props: Dict[Union[str, canberra.constants.Props], str] = None, id: int = 0, on_finished: Union[Callable[[ForwardRef('Context'), int, Union[canberra.constants.Errors, canberra._canberra.CanberraError], Any], Any], Callable[[ForwardRef('Context'), int, Union[canberra.constants.Errors, canberra._canberra.CanberraError]], Any]] = None, user_data=<object object at 0x7f409c79ed00>, **other_props: str) → None

Play one event sound

id can be any numeric value which later can be used to cancel an event sound that is currently being played. You may use the same id twice or more times if you want to cancel multiple event sounds with a single cancel() call. It is recommended to pass 0 (the default) for the id if the event sound shall never be canceled.

If the requested sound is not cached in the server yet, this call might result in the sample being uploaded temporarily or permanently (this may be controlled with CANBERRA_CACHE_CONTROL).

This method will start playback in the background. It will not wait to return until playback completed. Depending on the backend used, a sound that is started shortly before your application terminates might or might not continue to play after your application terminated. If you want to make sure that all sounds finish to play, you need to pass an on_finished callback and wait for it to be called before you terminate your application.

The sample to play is identified by the EVENT_ID property. If it is already cached in the server the cached version is played. The properties passed in this call are merged with the properties supplied when the sample was cached (if applicable) and the context properties as set with change_props().

If EVENT_ID is not defined, the sound file passed in the MEDIA_FILENAME is played.

On Linux/Unix, the right sound to play is determined according to EVENT_ID, APPLICATION_LANGUAGE/MEDIA_LANGUAGE, the system locale, CANBERRA_XDG_THEME_NAME and CANBERRA_XDG_THEME_OUTPUT_PROFILE, following the XDG Sound Theming Specification. On non-Unix systems, the native event sound that matches the XDG sound name in EVENT_ID is played.

Parameters
  • props – A mapping of Props to values describing additional properties for this sound event.

  • id – An integer id this sound can later be identified with when calling cancel()

  • on_finished

    An optional callback to be called when the sound finishes playing. Depending on whether user_data is passed, the prototype for this callback will be:

    # without user_data
    def callback(ctx: Context, id: int, error: Union[CanberraError, Errors])
    
    # with user_data
    def callback(ctx: Context, id: int, error: Union[CanberraError, Errors], user_data: Any)
    

  • user_data – An optional argument to be passed to the on_finished callback

  • other_propsProps may also be passed as kwargs, where {Props.EVENT_ID: 'bell'} is passed as event_id='bell', which describe additional properties for this sound event.

cancel(self, id: int = 0) → None

Cancel one or more event sounds that have been started via play()

If callback function was passed to play() when starting the sound, calling cancel() might cause this callback function to be called with CANCELED as the error code (wrapped in CanberraError).

Parameters

id – The ID that identifies the sound(s) to cancel.

playing(self, id: int = 0) → bool

Check if at least one sound with the specified id is still playing

Parameters

id – The ID that identifies the sound(s) to check

Returns

True if at least one sound with the specified ID is still playing, and False if no sounds with the specified ID are still playing

Constants

class canberra.Props

Properties that describe sounds being played

Note

Any methods that accept Props values will also accept them as kwargs, using the lowercased attribute name

ctx = Context({Props.APPLICATION_NAME: 'My Application'})
# or
ctx = Context(application_name='My Application')
MEDIA_NAME = 'media.name'

A name describing the media being played. Localized if possible and applicable.

MEDIA_TITLE = 'media.title'

A (song) title describing the media being played. Localized if possible and applicable.

MEDIA_ARTIST = 'media.artist'

The artist of this media. Localized if possible and applicable.

MEDIA_LANGUAGE = 'media.language'

The language this media is in, in some standard POSIX locale string, such as "de_DE".

MEDIA_FILENAME = 'media.filename'

The file name this media was or can be loaded from.

MEDIA_ICON = 'media.icon'

An icon for this media in binary PNG format.

MEDIA_ICON_NAME = 'media.icon_name'

An icon name as defined in the XDG icon naming specification.

MEDIA_ROLE = 'media.role'

The “role” this media is played in. For event sounds the string "event". For other cases, strings like "music", "video", "game", …

EVENT_ID = 'event.id'

A textual id for an event sound, as mandated by the XDG sound naming specification.

EVENT_DESCRIPTION = 'event.description'

A descriptive string for the sound event. Localized if possible and applicable.

EVENT_MOUSE_X = 'event.mouse.x'

If this sound event was triggered by a mouse input event, the X position of the mouse cursor on the screen, formatted as string.

EVENT_MOUSE_Y = 'event.mouse.y'

If this sound event was triggered by a mouse input event, the Y position of the mouse cursor on the screen, formatted as string.

EVENT_MOUSE_HPOS = 'event.mouse.hpos'

If this sound event was triggered by a mouse input event, the X position of the mouse cursor as fractional value between 0 and 1, formatted as string, 0 reflecting the left side of the screen, 1 the right side.

EVENT_MOUSE_VPOS = 'event.mouse.vpos'

If this sound event was triggered by a mouse input event, the Y position of the mouse cursor as fractional value between 0 and 1, formatted as string, 0 reflecting the top end of the screen, 1 the bottom end.

EVENT_MOUSE_BUTTON = 'event.mouse.button'

If this sound event was triggered by a mouse input event, the number of the mouse button that triggered it, formatted as string. 1 for left mouse button, 3 for right, 2 for middle.

WINDOW_NAME = 'window.name'

If this sound event was triggered by a window on the screen, the name of this window as human readable string.

WINDOW_ID = 'window.id'

If this sound event was triggered by a window on the screen, some identification string for this window, so that the sound system can recognize specific windows.

WINDOW_ICON = 'window.icon'

If this sound event was triggered by a window on the screen, binary icon data in PNG format for this window.

WINDOW_ICON_NAME = 'window.icon_name'

If this sound event was triggered by a window on the screen, an icon name for this window, as defined in the XDG icon naming specification.

WINDOW_X = 'window.x'

If this sound event was triggered by a window on the screen, the X position of the window measured from the top left corner of the screen to the top left corner of the window.

Since: 0.17

WINDOW_Y = 'window.y'

If this sound event was triggered by a window on the screen, the y position of the window measured from the top left corner of the screen to the top left corner of the window.

Since: 0.17

WINDOW_WIDTH = 'window.width'

If this sound event was triggered by a window on the screen, the pixel width of the window.

Since: 0.17

WINDOW_HEIGHT = 'window.height'

If this sound event was triggered by a window on the screen, the pixel height of the window.

Since: 0.17

WINDOW_HPOS = 'window.hpos'

If this sound event was triggered by a window on the screen, the X position of the center of the window as fractional value between 0 and 1, formatted as string, 0 reflecting the left side of the screen, 1 the right side.

Since: 0.17

WINDOW_VPOS = 'window.vpos'

If this sound event was triggered by a window on the screen, the Y position of the center of the window as fractional value between 0 and 1, formatted as string, 0 reflecting the top side of the screen, 1 the bottom side.

Since: 0.17

WINDOW_DESKTOP = 'window.desktop'

If this sound event was triggered by a window on the screen and the windowing system supports multiple desktops, a comma separated list of indexes of the desktops this window is visible on. If this property is an empty string, it is visible on all desktops (i.e. ‘sticky’). The first desktop is 0. (e.g. "0,2,3")

Since: 0.18

WINDOW_X11_DISPLAY = 'window.x11.display'

If this sound event was triggered by a window on the screen and the windowing system is X11, the X display name of the window (e.g. ":0").

WINDOW_X11_SCREEN = 'window.x11.screen'

If this sound event was triggered by a window on the screen and the windowing system is X11, the X screen id of the window formatted as string (e.g. "0").

WINDOW_X11_MONITOR = 'window.x11.monitor'

If this sound event was triggered by a window on the screen and the windowing system is X11, the X monitor id of the window formatted as string (e.g. "0").

WINDOW_X11_XID = 'window.x11.xid'

If this sound event was triggered by a window on the screen and the windowing system is X11, the XID of the window formatted as string.

APPLICATION_NAME = 'application.name'

The name of the application this sound event was triggered by as human readable string (e.g. "GNU Emacs"). Localized if possible and applicable.

APPLICATION_ID = 'application.id'

An identifier for the program this sound event was triggered by. (e.g. “org.gnu.emacs”).

APPLICATION_VERSION = 'application.version'

A version number for the program this sound event was triggered by. (e.g. "22.2")

APPLICATION_ICON = 'application.icon'

Binary icon data in PNG format for the application this sound event is triggered by.

APPLICATION_ICON_NAME = 'application.icon_name'

An icon name for the application this sound event is triggered by, as defined in the XDG icon naming specification.

APPLICATION_LANGUAGE = 'application.language'

The locale string the application that is triggering this sound event is running in. A POSIX locale string such as de_DE@euro.

APPLICATION_PROCESS_ID = 'application.process.id'

The unix PID of the process that is triggering this sound event, formatted as string.

APPLICATION_PROCESS_BINARY = 'application.process.binary'

The path to the process binary of the process that is triggering this sound event.

APPLICATION_PROCESS_USER = 'application.process.user'

The user that owns the process that is triggering this sound event.

APPLICATION_PROCESS_HOST = 'application.process.host'

The host name of the host the process that is triggering this sound event runs on.

CANBERRA_CACHE_CONTROL = 'canberra.cache-control'

A special property that can be used to control the automatic sound caching of sounds in the sound server. One of "permanent", "volatile", "never". "permanent" will cause this sample to be cached in the server permanently. This is useful for very frequently used sound events such as those used for input feedback. "volatile" may be used for caching sounds in the sound server temporarily. They will expire after some time or on cache pressure. Finally, "never" may be used for sounds that should never be cached, because they are only generated very seldomly or even only once at most (such as desktop login sounds).

If this property is not explicitly passed to Context.play() it will default to "never". If it is not explicitly passed to Context.cache() it will default to “permanent”.

If the list of properties is handed on to the sound server this property is stripped from it.

CANBERRA_VOLUME = 'canberra.volume'

A special property that can be used to control the volume this sound event is played in if the backend supports it. A floating point value for the decibel multiplier for the sound. 0 dB relates to zero gain, and is the default volume these sounds are played in.

NOTE: the value of this must be in decibels, not in amplitudes,

e.g., from 0.0 to 1.0.

If the list of properties is handed on to the sound server this property is stripped from it.

CANBERRA_XDG_THEME_NAME = 'canberra.xdg-theme.name'

A special property that can be used to control the XDG sound theme that is used for this sample.

If the list of properties is handed on to the sound server this property is stripped from it.

CANBERRA_XDG_THEME_OUTPUT_PROFILE = 'canberra.xdg-theme.output-profile'

A special property that can be used to control the XDG sound theme output profile that is used for this sample.

If the list of properties is handed on to the sound server this property is stripped from it.

CANBERRA_ENABLE = 'canberra.enable'

A special property that can be used to control whether any sounds are played at all. If this property is "1" or unset sounds are played as normal. However, if it is "0" all calls to Context.play() will fail with DISABLED.

If the list of properties is handed on to the sound server this property is stripped from it.

CANBERRA_FORCE_CHANNEL = 'canberra.force_channel'

A special property that can be used to control on which channel a sound is played. The value should be one of mono, front-left, front-right, front-center, rear-left, rear-right, rear-center, lfe, front-left-of-center, front-right-of-center, side-left, side-right, top-center, top-front-left, top-front-right, top-front-center, top-rear-left, top-rear-right, top-rear-center.

This property is only honoured by some backends, other backends may choose to ignore it completely.

If the list of properties is handed on to the sound server this property is stripped from it.

Since: 0.13

class canberra.Errors

libcanberra error codes

Negative numbers represent errors; 0 represents success

SUCCESS = 0

Success

NOTSUPPORTED = -1

Operation not supported

INVALID = -2

Invalid argument

STATE = -3

Invalid state

OOM = -4

Out of memory

NODRIVER = -5

No such driver

SYSTEM = -6

System error

CORRUPT = -7

File or data corrupt

TOOBIG = -8

File or data too large

NOTFOUND = -9

File or data not found

DESTROYED = -10

Destroyed

CANCELED = -11

Canceled

NOTAVAILABLE = -12

Not available

ACCESS = -13

Access forbidden

IO = -14

IO error

INTERNAL = -15

Internal error

DISABLED = -16

Sound disabled

FORKED = -17

Process forked

DISCONNECTED = -18

Disconnected