![]() |
![]() |
![]() |
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. |