DBus API

Headless mode

Viewport DBus API

The pigment plugin exports a DBus API so that external applications can show or hide the viewport window programmatically. In addition, the plugin checks if the command line argument --headless is passed to start Elisa, in which case it starts with the viewport window hidden. Headless mode is the default when Elisa is automatically started by DBus.

The plugin opens a connection to the session bus, under the com.fluendo.Elisa name. Under this name, it registers the /com/fluendo/Elisa/Plugins/Pigment/Frontend object. The object implements the com.fluendo.Elisa.Plugins.Pigment.Frontend interface which can be used to show or hide the viewport.

com.fluendo.Elisa.Plugins.Pigment.Frontend Interface

class Frontend

Interface implemented by the /com/fluendo/Elisa/Plugins/Pigment/Frontend object.

Methods

show()

Show the viewport window.

Returns:nothing

hide()

Hide the viewport window.

Returns:nothing

Browser API

The poblesec plugin implements a DBus API to programmatically activate specific parts of the user interface.

The plugin opens a connection to the session bus, with the com.fluendo.Elisa name. In the connection it registers an object having the path /com/fluendo/Elisa/Plugins/Poblesec/Browser. The object implements the com.fluendo.Elisa.Plugins.Poblesec.Browser interface, which can be used to browse certain sections of the user interface.

com.fluendo.Elisa.Plugins.Poblesec.Browser Interface

class Browser

Interface implemented by the object registered at /com/fluendo/Elisa/Plugins/Poblesec/Browser`.

Methods

browse_photo_album(path)

Open the photo album located at album_path inside Elisa.

Parameters:

• path (string) – absolute path to a photo album name

Returns:

nothing

start_photo_album_slideshow(path)

Open the photo album located at album_path inside the slideshow.

Parameters:

• path (string) – absolute path to a photo album name

Returns:

nothing

browse_music_album(artist_name, album_name)

Open a music album in Elisa. artist_name and album_name must be present in the database.

Parameters:

• artist_name (string) – artist name
• album_name (string) – album name

Returns:

nothing

browse_section(section_name)

Open the specified section inside Elisa.

Parameters:

• section_name (string) – one of ‘Music’, ‘Video’ or ‘Pictures’

Returns:

nothing

Database DBus API

The database plugin exposes a DBus API for external applications to interact with our database without having to use SQL. It also allows to control the media scanning process.

The following objects are registered for com.fluendo.Elisa:

• /com/fluendo/Elisa/Plugins/Database/Photo, for photo related functions
• /com/fluendo/Elisa/Plugins/Database/Music, for music related functions

Photo

External applications can get a list of photo albums and relative pictures by calling methods on the /com/fluendo/Elisa/Plugins/Database/Photo object, which implements the com.fluendo.Elisa.Plugins.Database.Photo interface.

com.fluendo.Elisa.Plugins.Database.Photo Interface

class Photo

Interface of the object registered at /com/fluendo/Elisa/Plugins/Database/Photo. It can be used to get a list of photo albums and their pictures.

Methods

get_albums(start, count)

Get a range of album names to return from the list of photo albums sorted in alphanumerical order. The range starts at start and contains up to count elements.

Parameters:

• start (integer) – index of the first album to return
• count (integer) – maximum number of albums to return

Returns:

album names

Return type:

array of strings

get_album_pictures(album_name)

Get the list of absolute pathnames to the pictures contained in the album album_name. album_name is the name of an album as returned by get_albums(). If the album doesn’t exist in the database, PhotoAlbumNotFoundError is raised.

Parameters:

• album_name (string) – name of the album to get the pictures for

Returns:

absolute paths pointing to pictures belonging to the album

Return type:

array of strings

get_last_displayed_picture()

Get the last displayed picture. Note that only local pictures indexed in the database are returned.

Returns:an array containing album_name, picture_path Return type:array of strings

Signals

last_displayed_picture(album_name, track_path)

The last_displayed_picture signal is emitted whenever a new picture is shown inside Elisa. Note that the signal is only emitted for local indexed pictures.

Parameters:

• album_name (string) – album name
• picture_path (string) – absolute path to the picture

Music

As for photo, external applications can access music related functionality by calling methods on the /com/fluendo/Elisa/Plugins/Database/Music object. The Music object implements the com.fluendo.Elisa.Plugins.Database.Music interface.

com.fluendo.Elisa.Plugins.Database.Music Interface

class Music

Interface of the object registered at /com/fluendo/Elisa/Plugins/Database/Music. It can be used to get a list of music albums and tracks.

Methods

get_albums(start, count)

Get a range of album names to return from the list of music albums sorted in alphanumerical order. The range starts at start and contains up to count elements. The return value is an array of arrays of strings, where inner arrays contain two strings representing artist name and album name respectively.

Parameters:

• start (integer) – index of the first album to return
• count (integer) – maximum number of albums to return

Returns:

array of (artist, album) string pairs

Return type:

array of arrays of strings

get_album_artwork(artist_name, album_name)

Get the absolute path to the artwork image for the given album. If the artist or the album don’t exist, ArtistNotFoundError or MusicAlbumNotFoundError are raised respectively.

Parameters:

• artist_name (string) – artist name
• album_name (string) – album name

Returns:

absolute path to the cover artwork image or the empty string

Return type:

string

get_album_tracks(artist_name, album_name)

Get the list of tracks in the album. A track is represented as a (track_name, track_path) string pair. If the artist or the album don’t exist, ArtistNotFoundError or MusicAlbumNotFoundError are raised respectively.

Parameters:

• artist_name (string) – artist name
• album_name (string) – album name

Returns:

an array of (track_name, track_path) string pairs

Return type:

array of arrays of strings

get_last_played_track()

Get the last played track. Only local tracks indexed in the database are returned.

Returns:an array containing artist_name, album_name, track_title, track_path Return type:array of strings

Signals

last_played_track(artist_name, album_name, track_name, track_path)

The last_played_track signal is emitted whenever a new track starts playing within Elisa. The signal is emitted only for local tracks contained in the database.

Parameters:

• artist_name (string) – artist name
• album_name (string) – album name
• track_name (string) – track name
• track_path (string) – absolute path to the track

Scanner

External applications can stop and restart the media scanning process of elisa by calling methods on the /com/fluendo/Elisa/Database/MediaScanner object, which implements the com.fluendo.Elisa.Plugins.Database.MediaScanner interface.

com.fluendo.Elisa.Plugins.Database.MediaScanner Interface

class MediaScanner

Interface of the object registered at /com/fluendo/Elisa/Plugins/Database/MediaScanner. It allows a basic control of the media scanning process in Elisa.

Methods

start()

(Re-)Start the scanning process from the beginning. If the scanning process is already running nothing happens. This does not stop and restart the scanning process. Please use the stop() method and wait for it before calling start() if you want to restart a running scan process from the beginning.

Returns:nothing

stop()

Stop the scanning process after the current file was beeen processed. Returns as soon as the scanning stopped.

Returns:nothing

Playback Control

AudioPlayer

External applications can control the audio player of elisa by calling methods on the /com/fluendo/Elisa/Plugins/Poblesec/AudioPlayer object. The AudioPlayer object implements the com.fluendo.Elisa.Plugins.Poblesec.AudioPlayer interface. This interface provides methods to control the audio player and signals triggered when some states of the audio player change.

com.fluendo.Elisa.Plugins.Poblesec.AudioPlayer Interface

class AudioPlayer

Interface of the object registered at /com/fluendo/Elisa/Plugins/Poblesec/AudioPlayer. It can be used to control the playback of audio items in elisa.

Methods

play_music_album(artist_name, album_name)

Enqueue all the tracks of the music album identified by artist_name and album_name and start the playback of the first track. If the artist or the album does not exist, ArtistNotFoundError or MusicAlbumNotFoundError is raised respectively.

FIXME: This method should be in the database plugin. A more generic playlist API (like clear_playlist etc.) here and a more explicit implementation for enqueuing (like enqueue_album) in the database plugins would be better.

Parameters:

• artist_name (string) – the name of the artist (present in the database)
• album_name (string) – the name of the album to play (present in the database)

Returns:

nothing

play_file(file_path)

Enqueue and play the given file.

Parameters:

• file_path (string) – the path of the file to play

Returns:

nothing

toggle_pause()

Toggle between the play/paused state. This is done asynchronously, you can check the result by connecting to the status_changed signal.

Returns:nothing

stop()

Stop the playback. This is done asynchronously, you can check the result by connecting to the status_changed signal.

Returns:nothing

next()

Stop the playback of the current track and jump to the next one in the playlist.

Returns:nothing

previous()

Stop the playback of the current track and jump to the previous one in the playlist.

Returns:nothing

set_volume(volume_level)

Set the volume to volume_level. Do not rely on the volume level you may have set previously, always use the volume_changed signal to know the current volume level (as someone else could have changed it).

Parameters:

• volume_level (integer) – the desired volume level in percent

Returns:

nothing

get_volume()

Retrieve the current volume level. Instead of doing a looping poll on this method it is mandatory to use the volume_changed signal to stay up to date about changes on the volume level.

Returns:the volume level in percent Return type:integer

get_position()

Retrieve the current position during playback. This is typically called in a loop. The position might not be available with some streams. In this case InformationNotAvailableError is raised.

Returns:the position in the currently played track (in nanoseconds) Return type:long

get_duration()

Retrieve the duration of the currently played track. You might want to update your duration each time the status_changed signal goes to playing to always have the correct information. The duration might not be available with some streams. In this case InformationNotAvailableError is raised.

Returns:the duration of the currently played track (in nanoseconds) Return type:long

get_metadata()

Retrieve metadata about the currently playing track. It returns an array containing the following information:

• path to the file
• title of the track
• track number
• artist(s)
• album name

You probably want to call this method every time the playback starts (and/or continues) so it is suggested to connect to the status_changed signal and call this method each time the state changes to playing.

Note: The information provided by this method may not be in sync with the database, it could have been obtained from another plugin (such as Shoutcast or DAAP). Therefore, you can get metadata for something not in the database.

Return type:array of strings

Signals

status_changed(new_state)

Emitted when the playback state changes.

Parameters:

• new_state (string) – the new state of the player, one of (‘loading’, ‘playing’, ‘paused’, ‘stopped’).

volume_changed(new_volume):

Emitted when the volume level changes.

Parameters:

• new_volume (integer) – the new volume level in percent