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
-
canberra.
play_file
(filename: Union[str, pathlib.Path], **other_props: str) → canberra._canberra.Context¶ Play the specified sound file
- Parameters
- 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 asevent_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 callingplay()
.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 callingplay()
.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()
orcache()
if not called explicitly. It is recommended to initialize application properties withchange_props()
(or when creatingContext
) 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 callingplay()
), 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.
-
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 acode
ofNOTSUPPORTED
.
-
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 sameid
twice or more times if you want to cancel multiple event sounds with a singlecancel()
call. It is recommended to pass0
(the default) for theid
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 withchange_props()
.If
EVENT_ID
is not defined, the sound file passed in theMEDIA_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
andCANBERRA_XDG_THEME_OUTPUT_PROFILE
, following the XDG Sound Theming Specification. On non-Unix systems, the native event sound that matches the XDG sound name inEVENT_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
callbackother_props¶ –
Props
may also be passed as kwargs, where{Props.EVENT_ID: 'bell'}
is passed asevent_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, callingcancel()
might cause this callback function to be called withCANCELED
as the error code (wrapped inCanberraError
).- 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, andFalse
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 namectx = 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
and1
, 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
and1
, 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 toContext.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 toContext.play()
will fail withDISABLED
.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
-