| LibRhythmCat Reference Manual | ||||
|---|---|---|---|---|
| Top | Description | Object Hierarchy | Signals | ||||
#include <rclib-core.h> struct RCLibCore; enum RCLibCoreAudioOutputType; struct RCLibCoreClass; enum RCLibCoreEQType; enum RCLibCoreErrorCode; struct RCLibCoreMetadata; enum RCLibCorePlaySource; enum RCLibCoreSourceType; gboolean rclib_core_audio_output_get (RCLibCoreAudioOutputType *output_type); gboolean rclib_core_audio_output_set (RCLibCoreAudioOutputType output_type); gboolean rclib_core_effect_plugin_add (GstElement *element); GList * rclib_core_effect_plugin_get_list (); void rclib_core_effect_plugin_remove (GstElement *element); void rclib_core_exit (); gboolean rclib_core_get_balance (gfloat *balance); gboolean rclib_core_get_eq (RCLibCoreEQType *type,gdouble *band); const gchar * rclib_core_get_eq_name (RCLibCoreEQType type); GObject * rclib_core_get_instance (); const RCLibCoreMetadata * rclib_core_get_metadata (); gboolean rclib_core_get_play_source (RCLibCorePlaySource *source_type,gpointer *source_reference,gchar **cookie); RCLibCoreSourceType rclib_core_get_source_type (); GstStateChangeReturn rclib_core_get_state (GstState *state,GstState *pending,GstClockTime timeout); gchar * rclib_core_get_uri (); gboolean rclib_core_get_volume (gdouble *volume); gboolean rclib_core_init (GError **error); gboolean rclib_core_pause (); gboolean rclib_core_play (); gboolean rclib_core_query_buffering_percent (gint *percent,gboolean *busy); gboolean rclib_core_query_buffering_range (gint64 *start,gint64 *stop,gint64 *estimated_total); gint rclib_core_query_channels (); gint rclib_core_query_depth (); gint64 rclib_core_query_duration (); gint64 rclib_core_query_position (); gint rclib_core_query_sample_rate (); gboolean rclib_core_set_balance (gfloat balance); gboolean rclib_core_set_eq (RCLibCoreEQType type,gdouble *band); gboolean rclib_core_set_position (gint64 pos); void rclib_core_set_uri (const gchar *uri); void rclib_core_set_uri_with_play_source (const gchar *uri,RCLibCorePlaySource source_type,gpointer source_reference,GDestroyNotify notify,const gchar *cookie); gboolean rclib_core_set_volume (gdouble volume); gulong rclib_core_signal_connect (const gchar *name,GCallback callback,gpointer data); void rclib_core_signal_disconnect (gulong handler_id); gboolean rclib_core_stop (); gboolean rclib_core_update_play_source (RCLibCorePlaySource source_type,gpointer source_reference,GDestroyNotify notify,const gchar *cookie);
"balance-changed" :Run First"buffer-probe" :Run First"buffering" :Run First"eos" :Run First"eq-changed" :Run First"error" :Run First"new-duration" :Run First"state-changed" :Run First"tag-found" :Run First"uri-changed" :Run First"volume-changed" :Run First
The RCLibCore is a class which plays audio files, controls the player, and manages sound effects. The core uses GStreamer as its backend.
struct RCLibCore;
The audio player core. The contents of the RCLibCore structure are private and should only be accessed via the provided API.
typedef enum {
RCLIB_CORE_AUDIO_OUTPUT_AUTO = 0,
RCLIB_CORE_AUDIO_OUTPUT_PULSEAUDIO = 1,
RCLIB_CORE_AUDIO_OUTPUT_ALSA = 2,
RCLIB_CORE_AUDIO_OUTPUT_OSS = 3,
RCLIB_CORE_AUDIO_OUTPUT_JACK = 4,
RCLIB_CORE_AUDIO_OUTPUT_WAVEFORM = 5
} RCLibCoreAudioOutputType;
The enum type for audio output plug-in selection.
| automatic audio output plug-in | |
| PulseAudio output plug-in | |
| ALSA output plug-in | |
| OSS audio output plug-in | |
| jack audio output plug-in | |
| waveform audio output plug-in |
typedef enum {
RCLIB_CORE_EQ_TYPE_NONE = 0,
RCLIB_CORE_EQ_TYPE_POP = 1,
RCLIB_CORE_EQ_TYPE_ROCK = 2,
RCLIB_CORE_EQ_TYPE_METAL = 3,
RCLIB_CORE_EQ_TYPE_DANCE = 4,
RCLIB_CORE_EQ_TYPE_ELECTRONIC = 5,
RCLIB_CORE_EQ_TYPE_JAZZ = 6,
RCLIB_CORE_EQ_TYPE_CLASSICAL = 7,
RCLIB_CORE_EQ_TYPE_BLUES = 8,
RCLIB_CORE_EQ_TYPE_VOCAL = 9,
RCLIB_CORE_EQ_TYPE_CUSTOM = 10
} RCLibCoreEQType;
The enum type for the equalizer in the core.
| no equalizer effect | |
| the pop style | |
| the rock style | |
| the metal style | |
| the dance style | |
| the electronic style | |
| the jazz style | |
| the classical style | |
| the blues style | |
| the vocal style | |
| the custom style |
typedef enum {
RCLIB_CORE_ERROR_OK = 0,
RCLIB_CORE_ERROR_ALREADY_INIT = 1,
RCLIB_CORE_ERROR_NOT_INIT = 2,
RCLIB_CORE_ERROR_MISSING_CORE_PLUGIN = 3,
RCLIB_CORE_ERROR_CREATE_BIN_FAILED = 4,
RCLIB_CORE_ERROR_LINK_FAILED = 5
} RCLibCoreErrorCode;
The enum type for core error messages.
| no error | |
| the core is already initialized | |
| the core is not initialized yet | |
| necessary plug-ins are missing | |
| cannot create necessary GstBin | |
| cannot link necessary GstElement |
struct RCLibCoreMetadata {
gchar *title;
gchar *artist;
gchar *album;
gchar *ftype;
gchar *genre;
guint bitrate;
gint64 duration;
gint track;
gint year;
GstBuffer *image;
};
The structure for metadata read from core.
gchar * |
the title |
gchar * |
the artist |
gchar * |
the album name |
gchar * |
the format information |
gchar * |
the genre |
guint |
the bitrate (unit: bit/s) |
| the duration of the music (unit: nanosecond) | |
gint |
the track number |
gint |
the year |
GstBuffer * |
the cover image buffer |
typedef enum {
RCLIB_CORE_PLAY_SOURCE_NONE = 0,
RCLIB_CORE_PLAY_SOURCE_PLAYLIST = 1,
RCLIB_CORE_PLAY_SOURCE_LIBRARY = 2,
RCLIB_CORE_PLAY_SOURCE_THIRDPARTY = 3
} RCLibCorePlaySource;
The enum type for play source.
typedef enum {
RCLIB_CORE_SOURCE_NONE = 0,
RCLIB_CORE_SOURCE_NORMAL = 1,
RCLIB_CORE_SOURCE_CUE = 2,
RCLIB_CORE_SOURCE_EMBEDDED_CUE = 3
} RCLibCoreSourceType;
The enum type for the source type.
gboolean rclib_core_audio_output_get (RCLibCoreAudioOutputType *output_type);
Get the audio output plug-in used in the player.
|
the audio output plug-in type. [out] |
Returns : |
Whether the operation succeeded. |
gboolean rclib_core_audio_output_set (RCLibCoreAudioOutputType output_type);
Set the audio output plug-in for the player.
|
the audio output plug-in type |
Returns : |
Whether the operation succeeded. |
gboolean rclib_core_effect_plugin_add (GstElement *element);
Add a new GStreamer sound effect plugin to the player. Notice that this operation must be done when the player is not in playing or paused state.
|
a new GStreamer sound effect plugin to add |
Returns : |
Whether the operation succeeded. |
GList * rclib_core_effect_plugin_get_list ();
Get the list of the sound effect plugins that added to the player.
Returns : |
The plugin list, please do not modify or free it. [element-type GstElement][transfer none] |
void rclib_core_effect_plugin_remove (GstElement *element);
Remove an existed GStreamer sound effect plugin to the player. Notice that this operation must be done when the player is not in playing or paused state.
|
a new GStreamer sound effect plugin to remove |
gboolean rclib_core_get_balance (gfloat *balance);
Get the position in stereo panorama.
|
return the value of the position in stereo panorama. [out][allow-none] |
Returns : |
Whether the balance position is read successfully. |
gboolean rclib_core_get_eq (RCLibCoreEQType *type,gdouble *band);
Get the equalizer of the player.
|
the equalizer style type. [out][allow-none] |
|
an array (10 elements) of the gains for each frequency band. [out][allow-none] |
Returns : |
Whether the data from equalizer is read successfully. |
const gchar * rclib_core_get_eq_name (RCLibCoreEQType type);
Get the name of the equalizer style type.
|
the equalizer style type |
Returns : |
The style name. |
GObject * rclib_core_get_instance ();
Get the running RCLibCore instance.
Returns : |
The running instance. [transfer none] |
const RCLibCoreMetadata * rclib_core_get_metadata ();
Get metadata read from the loaded file in the core.
Returns : |
The metadata. |
gboolean rclib_core_get_play_source (RCLibCorePlaySource *source_type,gpointer *source_reference,gchar **cookie);
Get the play source reference.
|
(allow-none): the source type. [out] |
|
(allow-none): the source reference. [out] |
|
(transfer full): (allow-none): the cookie for third-party play source. [out] |
Returns : |
Whether the play source returned. |
RCLibCoreSourceType rclib_core_get_source_type ();
Get source type of the URI.
Returns : |
The source type. |
GstStateChangeReturn rclib_core_get_state (GstState *state,GstState *pending,GstClockTime timeout);
Gets the state of the element.
|
a pointer to GstState to hold the state. Can be NULL. [out][allow-none] |
|
a pointer to GstState to hold the pending state. Can be NULL. [out][allow-none] |
|
a GstClockTime to specify the timeout for an async state change or GST_CLOCK_TIME_NONE for infinite timeout |
Returns : |
GST_STATE_CHANGE_SUCCESS if the element has no more pending state and the last state change succeeded, GST_STATE_CHANGE_ASYNC if the element is still performing a state change or GST_STATE_CHANGE_FAILURE if the last state change failed. MT safe. |
gchar * rclib_core_get_uri ();
Get the URI.
Returns : |
The URI, NULL if not set. |
gboolean rclib_core_get_volume (gdouble *volume);
Get the volume of the player.
|
the volume to return. [out][allow-none] |
Returns : |
Whether the volume is read successfully. |
gboolean rclib_core_init (GError **error);
Initialize the core, if the initialization failed, it returns FALSE,
and error will be set.
|
return location for a GError, or NULL |
Returns : |
Whether the initialization succeeded. |
gboolean rclib_core_pause ();
Set the state of the player to pause.
Returns : |
Whether the state is set to pause successfully. |
gboolean rclib_core_play ();
Set the state of the player to play.
Returns : |
Whether the state is set to play successfully. |
gboolean rclib_core_query_buffering_percent (gint *percent,gboolean *busy);
Get the percentage of buffered data. This is a value between 0 and 100. The busy indicator is TRUE when the buffering is in progress.
|
the buffering percent (0-100). [out][allow-none] |
|
if buffering is busy. [out][allow-none] |
Returns : |
Whether the query succeeded. |
gboolean rclib_core_query_buffering_range (gint64 *start,gint64 *stop,gint64 *estimated_total);
gint rclib_core_query_channels ();
Get the channel number of the playing stream.
Returns : |
The channel number. |
gint rclib_core_query_depth ();
Get the depth of the playing stream.
Returns : |
The depth. |
gint64 rclib_core_query_duration ();
Return the duration of the music set on this player (in nanosecond).
Returns : |
The duration (in nanosecond). |
gint64 rclib_core_query_position ();
Get the playing position in the player (in nanosecond).
Returns : |
The playing position (in nanosecond). |
gint rclib_core_query_sample_rate ();
Get the sample rate of the playing stream.
Returns : |
The sample rate (unit: Hz). |
gboolean rclib_core_set_balance (gfloat balance);
Set the position in stereo panorama.
|
set the position in stereo panorama |
Returns : |
Whether the balance position is set successfully. |
gboolean rclib_core_set_eq (RCLibCoreEQType type,gdouble *band);
Set the equalizer of the player.
|
the equalizer style type |
|
an array (10 elements) of the gains for each frequency band |
Returns : |
Whether the equalizer is set successfully. |
gboolean rclib_core_set_position (gint64 pos);
Set the position for the player (in nanosecond). Notice that this function can only be used when this player is playing or paused.
|
the position to set |
Returns : |
Whether the operation succeeded. |
void rclib_core_set_uri (const gchar *uri);
Set the URI to play.
|
the URI to play |
void rclib_core_set_uri_with_play_source (const gchar *uri,RCLibCorePlaySource source_type,gpointer source_reference,GDestroyNotify notify,const gchar *cookie);
Set the URI and the music source reference to play.
|
the URI to play |
|
the source type |
|
the source reference. [allow-none] |
|
the reference destroy notify. [allow-none] |
|
he cookie for third-party play item. [allow-none] |
gboolean rclib_core_set_volume (gdouble volume);
Set the volume of the player.
|
the volume of the player, it should be between 0.0 and 1.0. |
Returns : |
Whether the volume is set successfully. |
gulong rclib_core_signal_connect (const gchar *name,GCallback callback,gpointer data);
Connect the GCallback function to the given signal for the running instance of RCLibCore object.
|
the name of the signal |
|
the the GCallback to connect. [scope call] |
|
the user data |
Returns : |
The handler ID. |
void rclib_core_signal_disconnect (gulong handler_id);
Disconnects a handler from the running core instance so it will not be called during any future or currently ongoing emissions of the signal it has been connected to. The handler_id becomes invalid and may be reused.
|
handler id of the handler to be disconnected |
gboolean rclib_core_stop ();
Set the player to stop state.
Returns : |
Whether the state is set to stop successfully. |
gboolean rclib_core_update_play_source (RCLibCorePlaySource source_type,gpointer source_reference,GDestroyNotify notify,const gchar *cookie);
Update the source reference.
|
the source type |
|
the source reference. [allow-none] |
|
the reference destroy notify. [allow-none] |
|
he cookie for third-party play item. [allow-none] |
Returns : |
Whether the source reference updated successfully. |
"balance-changed" signalvoid user_function (RCLibCore *core,
gfloat balance,
gpointer user_data) : Run First
The ::balance-changed signal is emitted when new balance was applied.
|
the RCLibCore that received the signal |
|
the balance value (from -1.0 (left) to 1.0 (right)) |
|
user data set when the signal handler was connected. |
"buffer-probe" signalvoid user_function (RCLibCore *core,
gpointer buffer,
gpointer caps,
gpointer user_data) : Run First
The ::buffering signal is emitted when the buffer data pass through the pipeline. Warning: This signal is emitted from the working thread of GStreamer.
"buffering" signalvoid user_function (RCLibCore *core,
gint percent,
gpointer user_data) : Run First
The ::buffering signal is emitted when the core is buffering.
|
the RCLibCore that received the signal |
|
the buffering percent (0-100) |
|
user data set when the signal handler was connected. |
"eos" signalvoid user_function (RCLibCore *core,
gpointer user_data) : Run First
The ::eos signal is emitted when end-of-stream reached in the current pipeline of the core.
|
the RCLibCore that received the signal |
|
user data set when the signal handler was connected. |
"eq-changed" signalvoid user_function (RCLibCore *core,
guint type,
gpointer values,
gpointer user_data) : Run First
The ::eq-changed signal is emitted when new equalizer settings were applied.
"error" signalvoid user_function (RCLibCore *core,
gchar *arg1,
gpointer user_data) : Run First
The ::error signal is emitted when any error in the core occurs.
|
the RCLibCore that received the signal |
|
user data set when the signal handler was connected. |
"new-duration" signalvoid user_function (RCLibCore *core,
gint64 duration,
gpointer user_data) : Run First
The ::new-duration signal is emitted when new duration information was found.
|
the RCLibCore that received the signal |
|
the duration (unit: nanosecond) |
|
user data set when the signal handler was connected. |
"state-changed" signalvoid user_function (RCLibCore *core,
gint state,
gpointer user_data) : Run First
The ::state-changed signal is emitted when the state of the core is changed.
|
the RCLibCore that received the signal |
|
the state of the core |
|
user data set when the signal handler was connected. |
"tag-found" signalvoid user_function (RCLibCore *core,
gpointer metadata,
gchar *uri,
gpointer user_data) : Run First
The ::tag-found signal is emitted when new metadata (tag) was found. Notice that this signal may be emitted many times during the playing.
|
the RCLibCore that received the signal |
|
the metadata |
|
the URI |
|
user data set when the signal handler was connected. |
"uri-changed" signalvoid user_function (RCLibCore *core,
gchar *uri,
gpointer user_data) : Run First
The ::uri-changed signal is emitted when new URI was set.
|
the RCLibCore that received the signal |
|
the URI |
|
user data set when the signal handler was connected. |
"volume-changed" signalvoid user_function (RCLibCore *core,
gdouble volume,
gpointer user_data) : Run First
The ::volume-changed signal is emitted when the volume was changed.
|
the RCLibCore that received the signal |
|
the volume (from 0.0 to 1.0) |
|
user data set when the signal handler was connected. |