Namespace

RB – 3.0

Programming interfaces available to Rhythmbox plugins.

Version3.4.7
AuthorsRhythmbox contributors
LicenseGPL-2.0-or-later
Websitehttps://gnome.pages.gitlab.gnome.org/rhythmbox/
Sourcehttps://gitlab.gnome.org/GNOME/rhythmbox

Dependencies

GObject—2.0 The base type system library
Browse documentation
Gio—2.0 GLib I/O library
Browse documentation
Gst—1.0 GStreamer media framework
Browse documentation
Gtk—3.0 The GTK toolkit
Browse documentation

Classes

Application

RBApplication contains some interactions with the desktop environment, such as the app menu and processing of files specified on the command line.

AsyncCopy

AutoPlaylistSource

A playlist populated with the results of a database query.

BrowserSource

This class simplifies implementation of sources that include genre/artist/album browsers. It also handles searching (using the search box) and a few other UI niceties.

ButtonBar

CellRendererPixbuf

This is similar to GtkCellRendererPixbuf, except that it also emits a signal when the pixbuf is clicked on, and it can only use pixbuf objects.

CellRendererRating

This cell renderer is used to display song ratings in the RBEntryView, and allows the user to modify ratings directly in the track listing.

ChunkLoader

DisplayPage

This is the base class for items that appear in the display page tree and can occupy the main display area. Sources and source groups are display pages. Other types of display, such as music visualization, could be implemented as display pages too.

DisplayPageGroup

Page groups define sections of the display page tree. A page group consists of an internal name, a display name, and a category. The internal name can be used to locate a registered page group. The category is used to sort the page groups.

DisplayPageModel

The RBDisplayPageTree widget is backed by a GtkTreeStore containing the sources and a set of attributes used to structure and display them, and a GtkTreeModelFilter that hides sources with the visibility property set to FALSE. This class implements the filter model and also creates the actual model.

DisplayPageTree

The display page tree widget is a GtkTreeView backed by a GtkListStore containing the display page instances (sources and other things). Display pages include sources, such as the library and playlists, and other things like the visualization display.

EncoderFactory

EntryView

This class provides a predefined set of columns for displaying the common set of RhythmDBEntry properties, but also allows custom columns to be appended. The ‘playing’ column is always created as the first column in the tree view, displaying a playing or paused image next to the currently playing entry, and also an error image next to entries for which a playback error message has been set. Clicking on the error image opens a dialog displaying the full message.

ExtDB

This class simplifies searching for and providing external metadata such as album art or lyrics. A metadata provider connects to a signal on the database and in response provides a URI, a buffer containing the data, or an object representation of the data (such as a GdkPixbuf). A metadata requestor calls rb_ext_db_request and specifies a callback, or alternatively connects to a signal to receive all metadata as it is stored.

FadingImage

This widget displays images, performing a simple fade transition between them. It also emits signals when URIs or pixbufs are dropped onto it.

History

RBHistory is a GSequence that maintains a “current” pointer and can delete an arbitrary element in amortized O(log(N)) time. It can call a deletion callback when it removes one of its entries.

LibraryBrowser

This widget contains a set of RBPropertyViews backed by RhythmDBPropertyModels and constructs a chain of RhythmDBQueryModels to perform filtering of the entries in a source.

ListModel

Stores a list of items and emits notification signals on changes.

MediaPlayerEntryType

MediaPlayerSource

MetaData

Provides a simple synchronous interface for metadata extraction and updating.

PlaylistManager

The playlist manager loads and saves the on-disk playlist file, provides UI actions and a DBus interface for dealing with playlists, and internal interfaces for creating playlists.

PlaylistSource

This class provides some common infrastructure for playlist sources. A playlist, in this context, is a persistent user-defined selection from a set of songs. Playlists (static and auto) based on the main library are saved to the playlists.xml file stored alongside the rhythmdb.xml file. Playlists on portable music players are saved on the device in the format the player itself supports.

PlayOrder

A play order defines an ordering of the entries from a RhythmDBQueryModel that the RBShellPlayer uses to get the next or previous entry to play.

PodcastManager

PodcastSearch

PodcastSearchITunes

PropertyView

A simple GtkTreeView that displays the contents of a RhythmDBPropertyModel. The first row in the tree view displays the total number of properties and entries, in the form “All 473 artists (6241)”. Each subsequent row in the tree view displays a property value and the number of entries from the RhythmDBQueryModel with that value.

Rating

This widget displays a rating (0-5 stars) and allows the user to alter the rating by clicking.

RemovableMediaManager

The removable media manager maintains the mapping between GIO GVolume and GMount objects and rhythmbox sources.

RhythmDB

RhythmDB is an in-memory database containing RhythmDBEntry items. It runs queries represented as GPtrArrays containing query criteria, feeding the results into RhythmDBQueryResults implementations such as RhythmDBQueryModel. From there, entries are grouped by particular property values to form RhythmDBPropertyModels.

RhythmDBEntryType

This is the base class for database entry type classes, which provide some aspects of the behaviour of database entry types. There are different entry types for songs, radio streams, podcast feeds and episodes, and so on.

RhythmDBImportJob

Tracks the addition to the database of files under a set of directories, providing status information.

RhythmDBPropertyModel

A RhythmDBPropertyModel groups the entries in a RhythmDBQueryModel by the value of a property. For example, a RhythmDBPropertyModel using the RHYTHMDB_PROP_ARTIST property can be used as the model for a GtkTreeView that will list the artists present in the query model.

RhythmDBQueryModel

A RhythmDBQueryModel contains an ordered set of RhythmDBEntry items, either generated by running a query against the database, or populated by adding individual entries.

RhythmDBQueryResultList

SearchEntry

The search entry contains a label and a text entry box. The text entry box contains an icon that acts as a ‘clear’ button.

SegmentedBar

Shell

RBShell is the main application class in Rhythmbox. It creates and holds references to the other main objects (RBShellPlayer, RhythmDB, RBDisplayPageTree), constructs the main window UI, and provides the basic DBus interface.

ShellPlayer

The shell player (or player shell, depending on who you’re talking to) manages the RBPlayer instance, tracks the current playing RhythmDBEntry, and manages the various RBPlayOrder instances. It provides simple operations such as next, previous, play/pause, and seek.

ShellPreferences

The preferences dialog is built around a GtkNotebook widget, with two built-in pages and additional pages for various sources.

SongInfo

Displays song properties and, if we know how to edit tags in the file, allows the user to edit them.

Source

This class provides methods for requesting information about the UI capabilities of the source, and defines the expectations that apply to all sources - that they will provide RBEntryView and RhythmDBQueryModel objects, mostly.

SourceSearch

These translate the text in the search entry box into a RhythmDBQuery. The basic implementation will return a query like RHYTHMDB_QUERY_PROP_LIKE, RHYTHMDB_PROP_SEARCH_MATCH, text. Simple variants can restrict the search to single properties (artist, album, genre). More complicated searches could implement something like the Xesam User Query spec.

SourceSearchBasic

This implementation of RBSourceSearch constructs queries that search on a single RhythmDBEntry property. It’s useful for providing basic searches.

SourceToolbar

This class combines a toolbar for custom source actions with a search entry. The toolbar content is specified using a UI path. The RBSourceToolbar takes care of preserving search state when the selected page changes, and performs searches when the user selects a new search type or changes the search text.

StaticPlaylistSource

Static playlists are not defined by a query, but instead by manually selected and ordered tracks.

StreamingSource

This class provides handling of buffering signals and streaming song metadata common to different types of sources that play continuous streaming media.

StringValueMap

Simplifies the use of string:GValue maps with respect to copying of the values inserted into the map. Except for rb_string_value_map_peek, the caller retains ownership of values passed in, and assumes ownership of all values returned.

TaskList

TaskProgressSimple

This implementation of RBTaskProgress can be used to represent tasks that aren’t bound to the lifecycle of an object that can implement the interface directly.

TrackTransferBatch

Manages the transfer of a set of tracks (using RBEncoder), providing overall status information and allowing the transfer to be cancelled as a single unit.

TrackTransferQueue

URIDialog

A simple dialog used to request a single URI from the user.

Interfaces

DeviceSource

Sources that represent physical devices should implement this interface. It exposes the ability to eject the device, and also can be used to implement some RBSource methods by using details from a GVolume or GMount accessed via ‘volume’ and ‘mount’ properties on the source object. Devices that are not based on a GVolume or GMount can still use the interface, but they must provide implementations of the can_eject and eject methods.

Encoder

The RBEncoder interface provides transcoding between audio formats based on encoding profiles. The encoder implementation operates asynchronously and provides status updates in the form of signals emitted on the main thread. A new encoder instance should be created for each file that is transcoded or copied.

Player

This is the interface implemented by the rhythmbox playback backends. It allows the caller to control playback (open, play, pause, close), seek (set_time), control volume (get_volume, set_volume) and receive playback state information (get_time, various signals).

PlayerGstFilter

This interface allows a caller to add filter elements to the GStreamer playback pipeline.

PlayerGstTee

This interface allows a caller to add a new sink to the GStreamer playback pipeline.

RhythmDBQueryResults

This is the interface that RhythmDB uses to report results of database queries. When running a query, it first calls rhythmdb_query_results_set_query, then passes entries matching the query to rhythmdb_query_results_add_results in batches, and finally calls rhythmdb_query_results_query_complete. There are no guarantees as to which threads the calls are made from.

TaskProgress

TransferTarget

Sources that can accept track transfers should implement this interface and call the associated functions to perform transfers. The source needs to be able to construct target URIs for transfers, and can optionally perform its own processing after transfers have finished. The source must also provide a GstEncodingTarget that describes the formats it accepts.

Structs

ExtDBKey

An external metadata key consists of one or more required fields (such as the album name for album art lookups), zero or more optional fields (such as the artist name), and zero or more informational fields (such as the musicbrainz album ID).

PodcastChannel

PodcastItem

Profiler

RefString

RhythmDBEntry

RhythmDBEntryChange

RhythmDBQueryData

Aliases

Enumerations

DisplayPageGroupCategory

DisplayPageGroupType

Predefined categories of page group. The order they’re defined here is the order they appear in the page tree.

DisplayPageModelColumn

Columns present in the display page model.

EntryViewColumn

Predefined column types to use in RBEntryViews. Use

rb_entry_view_append_column to add these to an entry view.

The predefined column names map directly to the RhythmDBEntry properties the columns display.

EntryViewState

ExtDBSourceType

GstMediaType

MetaDataError

MetaDataField

Metadata fields that can be read from and written to files.

MetadataFieldType

PlayerPlayType

PlaylistExportType

PlaylistManagerError

PodcastFeedUpdateStatus

PodcastParseStatus

RhythmDBEntryAvailability

Various events that can result in changes to the entry’s availability.

RhythmDBEntryCategory

Categories used to group entry types. These are used in a few places to control handling of entries.

RhythmDBError

RhythmDBPropertyModelColumn

RhythmDBPropType

RhythmDBQueryModelLimitType

RhythmDBQueryType

ShellActivationType

ShellError

ShellPrefsUILocation

Locations available for adding new widgets to the preferences dialog.

ShellUILocation

SourceEOFType

SourceLoadStatus

TaskOutcome

Functions

assert_locked

Asserts that mutex is currently locked. Does not work with all mutex implementations.

builder_boldify_label

Makes a label built from a GtkBuilder file bold.

builder_load

Locates and reads a GtkBuilder file, automatically connecting signal handlers where possible.

builder_load_plugin_file

Like #rb_builder_load, except it finds files associated with plugins as well as those in the core data directories.

canonicalise_uri

Converts uri to canonical URI form, ensuring it doesn’t contain any redundant directory fragments or unnecessarily escaped characters. All URIs passed to RhythmDB functions should be canonicalised.

check_dir_has_space

Checks that the filesystem holding file has at least bytes_needed bytes available.

check_dir_has_space_uri

Checks that the filesystem holding uri has at least bytes_needed bytes available.

collate_hash_table_keys

Returns a GList containing all keys from table. The keys are not copied.

collate_hash_table_values

Returns a GList containing all values from table. The values are not copied.

combo_box_hyphen_separator_func

A row separator function to use for GtkComboBox widgets. It expects the model to contain a string in its first column, and interprets a string containing a single hyphen character as a separator.

compare_gtimeval

Compares two GTimeVal structures for sorting.

copy_function

Just returns its first argument. Useful as a callback function.

debug_get_args

Constructs arguments to pass to another process using this debug output code that will produce the same debug output settings.

debug_init

Sets up debug output, with either all debug enabled or none.

debug_init_match

Sets up debug output, enabling debug output from file and function names that contain the specified match string.

debug_matches

Checks if file or func matches the current debug output settings.

debug_real

If the debug output settings match the function or file names, the debug message will be formatted and written to standard error.

debug_realf

If the debug output settings match the function or file names, the debug message will be formatted and written to standard error.

debug_stop_in_debugger

Raises a SIGINT signal to get the attention of the debugger. When not running under the debugger, we don’t want to stop, so we ignore the signal for just the moment that we raise it.

error_dialog

Creates and displays a simple error dialog box containing a primary message in bold, larger type and a secondary message in the regular font. Both the primary and secondary message strings should be translated.

false_function

Just returns FALSE, useful as a callback function.

file

Searches for an installed file, returning the full path name if found, NULL otherwise.

file_chooser_new

Creates and shows a regular gtk+ file chooser dialog with a given title. The user’s music directory (typically ~/Music) is added as a shortcut.

file_find_extant_parent

Walks up the filesystem hierarchy to find a GFile representing the nearest extant ancestor of the specified file, which may be the file itself if it exists.

file_helpers_init

Sets up file search paths for rb_file. Must be called on startup.

file_helpers_shutdown

Frees various data allocated by file helper functions. Should be called on shutdown.

file_resolve_symlink

Attempts to resolve symlinks leading to file and return a canonical location.

find_plugin_data_file

Locates a file under the plugin’s data directory.

find_plugin_resource

Constructs a resource path for a plugin data file.

find_user_cache_file

Determines the full path to use for user-specific cached files within the user cache directory.

find_user_data_file

Determines the full path to use for user-specific files, such as rhythmdb.xml, within the user data directory (see rb_user_data_dir).

gst_add_filter

Inserts a filter into the filter bin, using pad blocking (if requested) to avoid breaking the data flow. Pad blocking should be used when the pipeline is in PLAYING state, or when in PAUSED state where a streaming thread will be holding the stream lock for the filter bin.

gst_add_tee

Attaches a branch to the tee, using pad blocking (if requested) to avoid breaking the data flow. Pad blocking should be used when the pipeline is in PLAYING state, or when in PAUSED state where a streaming thread will be holding the stream lock for the filter bin.

gst_caps_to_media_type

gst_create_filter_bin

Creates an initial bin to use for dynamically plugging filter elements into the pipeline.

gst_encoder_set_encoding_style

gst_encoding_profile_get_encoder

gst_encoding_profile_get_encoder_caps

gst_encoding_profile_get_media_type

gst_encoding_profile_get_presets

gst_encoding_profile_get_settings

Returns a list of settings for the profile profile that can usefully be exposed to a user. This usually means just bitrate/quality settings. This works by finding the name of the encoder element for the profile and retrieving a list specific to that encoder.

gst_encoding_profile_set_preset

Applies the preset preset to the audio encoding profile within profile.

gst_error_get_error_code

Maps a GStreamer error to an RBPlayerError error code.

gst_get_default_encoding_target

gst_get_encoding_profile

gst_get_missing_plugin_type

gst_media_type_is_lossless

gst_media_type_matches_profile

gst_media_type_to_caps

gst_media_type_to_extension

gst_media_type_to_mime_type

gst_mime_type_to_media_type

gst_process_embedded_image

Converts embedded image data extracted from a tag list into a GdkPixbuf. The returned GdkPixbuf is owned by the caller.

gst_process_tag_string

Processes a tag string, determining the metadata field identifier corresponding to the tag name, and converting the tag data into the appropriate value type.

gst_remove_filter

Removes a filter from the filter bin, using pad blocking (if requested) to avoid breaking the data flow. Pad blocking should be used when the pipeline is in PLAYING state, or when in PAUSED state where a streaming thread will be holding the stream lock for the filter bin.

gst_remove_tee

Removes a branch from the tee, using pad blocking (if requested) to avoid breaking the data flow. Pad blocking should be used when the pipeline is in PLAYING state, or when in PAUSED state where a streaming thread will be holding the stream lock for the filter bin.

gvalue_compare

Compares a and b for sorting. a and b must contain the same value type for the comparison to be valid. Comparisons for some value types are not particularly useful.

is_main_thread

Checks if currently executing on the main thread.

list_deep_free

Frees each element of list and list itself.

list_destroy_free

Calls destroyer for each element in list, then frees list.

locale_dir

Returns the locale directory identified at build configuration time.

make_duration_string

Constructs a string describing the specified duration. The string describes hours, minutes, and seconds, and its format is localised.

make_elapsed_time_string

Constructs a string describing a playback position. The string describes hours, minutes, and seconds, and its format is localised. The string can describe either the elapsed time or the time remaining.

make_time_string

Constructs a string describing the specified time.

menu_update_link

Updates a submenu link to point to the specified target menu.

music_dir

Returns the default directory for the user’s music library. This will usually be the ‘Music’ directory under the home directory.

null_function

Just returns NULL. Useful as a callback function.

podcast_parse_channel_copy

podcast_parse_channel_new

podcast_parse_channel_ref

podcast_parse_channel_unref

podcast_parse_error_quark

podcast_parse_item_copy

podcast_parse_item_free

podcast_parse_load_feed

rhythmbox_get_resource

rhythmdb_query_get_type

safe_strcmp

sanitize_path_for_msdos_filesystem

Modifies path such that it represents a legal path for MS DOS filesystems. Note that it replaces forward slash characters, so it’s only appropriate for use with individual path segments rather than entire paths.

sanitize_uri_for_filesystem

Removes characters from uri that are not allowed by the filesystem on which it would be stored, or a specific type of filesystem if specified. At present, this only supports MS DOS filesystems.

scale_pixbuf_to_size

Creates a new GdkPixbuf from the original one, for a target of size, respecting the aspect ratio of the image.

search_fold

Returns a case-folded and punctuation-stripped version of original, useful for performing text searches.

set_tree_view_column_fixed_width

Sets a fixed size for a tree view column based on a set of strings to be displayed in the column.

settings_delayed_sync

Synchronizes settings in the settings instance after 500ms has elapsed with no further changes.

signal_accumulator_boolean_or

A GSignalAccumulator used to return the boolean OR of all returned (boolean) values.

signal_accumulator_object_handled

A GSignalAccumulator that aborts the signal emission after the first handler to return a value, and returns the value returned by that handler. This is the opposite behaviour from what you get when no accumulator is specified, where the last signal handler wins.

signal_accumulator_value_array

A GSignalAccumulator used to combine all returned values into a GArray of GValue instances.

signal_accumulator_value_handled

A GSignalAccumulator that aborts the signal emission after the first handler to return a value, and returns the value returned by that handler. This is the opposite behaviour from what you get when no accumulator is specified, where the last signal handler wins.

slist_deep_free

Frees each element of list and list itself.

stock_icons_init

Initializes the stock icons, adding the necessary filesystem locations to the GTK icon search path. Must be called on startup.

stock_icons_shutdown

If anything was necessary to clean up the stock icons, this function would do it. Doesn’t do anything, but should be called on shutdown anyway.

str_in_strv

Checks if needle is present in the NULL-terminated string array haystack.

string_list_contains

Checks if list contains the string s.

string_list_copy

Creates a deep copy of list.

string_list_equal

Checks if a and b contain exactly the same set of strings, regardless of order.

string_split_words

Splits string on word boundaries using Unicode character definitions.

threads_init

Initializes various thread helpers. Must be called on startup.

true_function

Just returns TRUE, useful as a callback function.

uri_append_path

Creates a new URI consisting of path appended to uri.

uri_append_uri

Creates a new URI consisting of fragment appended to uri. Generally isn’t a good idea.

uri_could_be_podcast

Checks if uri identifies a resource that is probably a podcast (RSS or Atom feed). This does not perform any IO, it just guesses based on the URI itself.

uri_create_parent_dirs

Ensures that all parent directories of uri exist so that uri itself can be created directly.

uri_exists

Checks if a URI identifies a resource that exists.

uri_get_dir_name

Returns the directory component of uri, that is, everything up to the start of the filename.

uri_get_filesystem_type

Returns a string describing the type of the filesystem containing uri.

uri_get_mount_point

Returns the mount point of the filesystem holding uri. If uri is on a normal filesystem mount (such as /, /home, /var, etc.) this will be NULL.

uri_get_short_path_name

Returns the filename component of uri, that is, everything after the final slash and before the start of the query string or fragment.

uri_handle_recursively

Calls func for each file found under the directory identified by uri. If uri identifies a file, calls func for that instead.

uri_handle_recursively_async

Calls func for each file found under the directory identified by uri, or if uri identifies a file, calls it once with that.

uri_is_descendant

Checks if uri refers to a path beneath ancestor, such that removing some number of path segments of uri would result in ancestor. It doesn’t do any filesystem operations, it just looks at the URIs as strings. The URI strings should be built by looking at a filesystem rather than user input, and must not have path segments that are empty (multiple slashes) or ‘.’ or ‘..’.

uri_is_directory

Checks if uri identifies a directory.

uri_is_hidden

Checks if uri is hidden, according to the Unix filename convention. If the filename component of uri begins with a dot, the file is considered hidden.

uri_is_local

Checks if uri identifies a local resource. Currently this just checks that it uses the ‘file’ URI scheme.

uri_is_readable

Checks if the user can read the resource identified by uri.

uri_is_writable

Checks if the user can write to the resource identified by uri.

uri_list_parse

Converts a single string containing a list of URIs into a GList of URI strings.

uri_make_hidden

Constructs a URI that is similar to uri but which identifies a hidden file. This can be used for temporary files that should not be visible to the user while they are in use.

uri_mkstemp

Creates a temporary file whose URI begins with prefix, returning the file URI and an output stream for writing to it.

uri_resolve_symlink

Attempts to resolve symlinks in uri and return a canonical URI for the file it identifies.

user_cache_dir

This will create the rhythmbox user cache directory, using the XDG Base Directory specification. If none of the XDG environment variables are set, this will be ~/.cache/rhythmbox.

user_data_dir

This will create the rhythmbox user data directory, using the XDG Base Directory specification. If none of the XDG environment variables are set, this will be ~/.local/share/rhythmbox.

value_array_append_data

Appends a single value to array, collecting it from Varargs.

value_free

Unsets and frees val. val must have been allocated using g_slice_new or g_slice_new0.

Function Macros

CHAIN_GOBJECT_METHOD

METADATA

METADATA_CLASS

profile_end

Records an end point for profiling. See rb_profile_start.

profile_start

Records a start point for profiling. This profile mechanism operates by issuing file access requests with filenames indicating the profile points. Use ‘strace -e access’ to gather this information.

RHYTHMDB

RHYTHMDB_CLASS

RHYTHMDB_ENTRY

RHYTHMDB_ENTRY_TYPE

RHYTHMDB_ENTRY_TYPE_CLASS

RHYTHMDB_IMPORT_JOB

RHYTHMDB_IMPORT_JOB_CLASS

RHYTHMDB_PROPERTY_MODEL

RHYTHMDB_PROPERTY_MODEL_CLASS

RHYTHMDB_QUERY

RHYTHMDB_QUERY_MODEL

RHYTHMDB_QUERY_MODEL_CLASS

RHYTHMDB_QUERY_RESULT_LIST

RHYTHMDB_QUERY_RESULT_LIST_CLASS

RHYTHMDB_QUERY_RESULTS

URI_DIALOG

URI_DIALOG_CLASS