RCLibCore

RCLibCore — The audio player core

Synopsis

#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);

Object Hierarchy

  GObject
   +----RCLibCore

Signals

  "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

Description

The RCLibCore is a class which plays audio files, controls the player, and manages sound effects. The core uses GStreamer as its backend.

Details

struct RCLibCore

struct RCLibCore;

The audio player core. The contents of the RCLibCore structure are private and should only be accessed via the provided API.


enum RCLibCoreAudioOutputType

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.

RCLIB_CORE_AUDIO_OUTPUT_AUTO

automatic audio output plug-in

RCLIB_CORE_AUDIO_OUTPUT_PULSEAUDIO

PulseAudio output plug-in

RCLIB_CORE_AUDIO_OUTPUT_ALSA

ALSA output plug-in

RCLIB_CORE_AUDIO_OUTPUT_OSS

OSS audio output plug-in

RCLIB_CORE_AUDIO_OUTPUT_JACK

jack audio output plug-in

RCLIB_CORE_AUDIO_OUTPUT_WAVEFORM

waveform audio output plug-in

struct RCLibCoreClass

struct RCLibCoreClass {
};

RCLibCore class.


enum RCLibCoreEQType

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.

RCLIB_CORE_EQ_TYPE_NONE

no equalizer effect

RCLIB_CORE_EQ_TYPE_POP

the pop style

RCLIB_CORE_EQ_TYPE_ROCK

the rock style

RCLIB_CORE_EQ_TYPE_METAL

the metal style

RCLIB_CORE_EQ_TYPE_DANCE

the dance style

RCLIB_CORE_EQ_TYPE_ELECTRONIC

the electronic style

RCLIB_CORE_EQ_TYPE_JAZZ

the jazz style

RCLIB_CORE_EQ_TYPE_CLASSICAL

the classical style

RCLIB_CORE_EQ_TYPE_BLUES

the blues style

RCLIB_CORE_EQ_TYPE_VOCAL

the vocal style

RCLIB_CORE_EQ_TYPE_CUSTOM

the custom style

enum RCLibCoreErrorCode

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.

RCLIB_CORE_ERROR_OK

no error

RCLIB_CORE_ERROR_ALREADY_INIT

the core is already initialized

RCLIB_CORE_ERROR_NOT_INIT

the core is not initialized yet

RCLIB_CORE_ERROR_MISSING_CORE_PLUGIN

necessary plug-ins are missing

RCLIB_CORE_ERROR_CREATE_BIN_FAILED

cannot create necessary GstBin

RCLIB_CORE_ERROR_LINK_FAILED

cannot link necessary GstElement

struct RCLibCoreMetadata

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 *title;

the title

gchar *artist;

the artist

gchar *album;

the album name

gchar *ftype;

the format information

gchar *genre;

the genre

guint bitrate;

the bitrate (unit: bit/s)

gint64 duration;

the duration of the music (unit: nanosecond)

gint track;

the track number

gint year;

the year

GstBuffer *image;

the cover image buffer

enum RCLibCorePlaySource

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.

RCLIB_CORE_PLAY_SOURCE_NONE

no play source

RCLIB_CORE_PLAY_SOURCE_PLAYLIST

the play source is playlist item

RCLIB_CORE_PLAY_SOURCE_LIBRARY

the play source is library item

RCLIB_CORE_PLAY_SOURCE_THIRDPARTY

the play source is third-party item

enum RCLibCoreSourceType

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.

RCLIB_CORE_SOURCE_NONE

the source is empty

RCLIB_CORE_SOURCE_NORMAL

the source is a normal audio file

RCLIB_CORE_SOURCE_CUE

the source is from CUE sheet file

RCLIB_CORE_SOURCE_EMBEDDED_CUE

the source is from embedded CUE sheet

rclib_core_audio_output_get ()

gboolean            rclib_core_audio_output_get         (RCLibCoreAudioOutputType *output_type);

Get the audio output plug-in used in the player.

output_type :

the audio output plug-in type. [out]

Returns :

Whether the operation succeeded.

rclib_core_audio_output_set ()

gboolean            rclib_core_audio_output_set         (RCLibCoreAudioOutputType output_type);

Set the audio output plug-in for the player.

output_type :

the audio output plug-in type

Returns :

Whether the operation succeeded.

rclib_core_effect_plugin_add ()

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.

element :

a new GStreamer sound effect plugin to add

Returns :

Whether the operation succeeded.

rclib_core_effect_plugin_get_list ()

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]

rclib_core_effect_plugin_remove ()

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.

element :

a new GStreamer sound effect plugin to remove

rclib_core_exit ()

void                rclib_core_exit                     ();

Unload the core.


rclib_core_get_balance ()

gboolean            rclib_core_get_balance              (gfloat *balance);

Get the position in stereo panorama.

balance :

return the value of the position in stereo panorama. [out][allow-none]

Returns :

Whether the balance position is read successfully.

rclib_core_get_eq ()

gboolean            rclib_core_get_eq                   (RCLibCoreEQType *type,
                                                         gdouble *band);

Get the equalizer of the player.

type :

the equalizer style type. [out][allow-none]

band :

an array (10 elements) of the gains for each frequency band. [out][allow-none]

Returns :

Whether the data from equalizer is read successfully.

rclib_core_get_eq_name ()

const gchar *       rclib_core_get_eq_name              (RCLibCoreEQType type);

Get the name of the equalizer style type.

type :

the equalizer style type

Returns :

The style name.

rclib_core_get_instance ()

GObject *           rclib_core_get_instance             ();

Get the running RCLibCore instance.

Returns :

The running instance. [transfer none]

rclib_core_get_metadata ()

const RCLibCoreMetadata * rclib_core_get_metadata       ();

Get metadata read from the loaded file in the core.

Returns :

The metadata.

rclib_core_get_play_source ()

gboolean            rclib_core_get_play_source          (RCLibCorePlaySource *source_type,
                                                         gpointer *source_reference,
                                                         gchar **cookie);

Get the play source reference.

source_type :

(allow-none): the source type. [out]

source_reference :

(allow-none): the source reference. [out]

cookie :

(transfer full): (allow-none): the cookie for third-party play source. [out]

Returns :

Whether the play source returned.

rclib_core_get_source_type ()

RCLibCoreSourceType rclib_core_get_source_type          ();

Get source type of the URI.

Returns :

The source type.

rclib_core_get_state ()

GstStateChangeReturn rclib_core_get_state               (GstState *state,
                                                         GstState *pending,
                                                         GstClockTime timeout);

Gets the state of the element.

state :

a pointer to GstState to hold the state. Can be NULL. [out][allow-none]

pending :

a pointer to GstState to hold the pending state. Can be NULL. [out][allow-none]

timeout :

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.

rclib_core_get_uri ()

gchar *             rclib_core_get_uri                  ();

Get the URI.

Returns :

The URI, NULL if not set.

rclib_core_get_volume ()

gboolean            rclib_core_get_volume               (gdouble *volume);

Get the volume of the player.

volume :

the volume to return. [out][allow-none]

Returns :

Whether the volume is read successfully.

rclib_core_init ()

gboolean            rclib_core_init                     (GError **error);

Initialize the core, if the initialization failed, it returns FALSE, and error will be set.

error :

return location for a GError, or NULL

Returns :

Whether the initialization succeeded.

rclib_core_pause ()

gboolean            rclib_core_pause                    ();

Set the state of the player to pause.

Returns :

Whether the state is set to pause successfully.

rclib_core_play ()

gboolean            rclib_core_play                     ();

Set the state of the player to play.

Returns :

Whether the state is set to play successfully.

rclib_core_query_buffering_percent ()

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.

percent :

the buffering percent (0-100). [out][allow-none]

busy :

if buffering is busy. [out][allow-none]

Returns :

Whether the query succeeded.

rclib_core_query_buffering_range ()

gboolean            rclib_core_query_buffering_range    (gint64 *start,
                                                         gint64 *stop,
                                                         gint64 *estimated_total);

rclib_core_query_channels ()

gint                rclib_core_query_channels           ();

Get the channel number of the playing stream.

Returns :

The channel number.

rclib_core_query_depth ()

gint                rclib_core_query_depth              ();

Get the depth of the playing stream.

Returns :

The depth.

rclib_core_query_duration ()

gint64              rclib_core_query_duration           ();

Return the duration of the music set on this player (in nanosecond).

Returns :

The duration (in nanosecond).

rclib_core_query_position ()

gint64              rclib_core_query_position           ();

Get the playing position in the player (in nanosecond).

Returns :

The playing position (in nanosecond).

rclib_core_query_sample_rate ()

gint                rclib_core_query_sample_rate        ();

Get the sample rate of the playing stream.

Returns :

The sample rate (unit: Hz).

rclib_core_set_balance ()

gboolean            rclib_core_set_balance              (gfloat balance);

Set the position in stereo panorama.

balance :

set the position in stereo panorama

Returns :

Whether the balance position is set successfully.

rclib_core_set_eq ()

gboolean            rclib_core_set_eq                   (RCLibCoreEQType type,
                                                         gdouble *band);

Set the equalizer of the player.

type :

the equalizer style type

band :

an array (10 elements) of the gains for each frequency band

Returns :

Whether the equalizer is set successfully.

rclib_core_set_position ()

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.

pos :

the position to set

Returns :

Whether the operation succeeded.

rclib_core_set_uri ()

void                rclib_core_set_uri                  (const gchar *uri);

Set the URI to play.

uri :

the URI to play

rclib_core_set_uri_with_play_source ()

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.

uri :

the URI to play

source_type :

the source type

source_reference :

the source reference. [allow-none]

notify :

the reference destroy notify. [allow-none]

cookie :

he cookie for third-party play item. [allow-none]

rclib_core_set_volume ()

gboolean            rclib_core_set_volume               (gdouble volume);

Set the volume of the player.

volume :

the volume of the player, it should be between 0.0 and 1.0.

Returns :

Whether the volume is set successfully.

rclib_core_signal_connect ()

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.

name :

the name of the signal

callback :

the the GCallback to connect. [scope call]

data :

the user data

Returns :

The handler ID.

rclib_core_signal_disconnect ()

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 :

handler id of the handler to be disconnected

rclib_core_stop ()

gboolean            rclib_core_stop                     ();

Set the player to stop state.

Returns :

Whether the state is set to stop successfully.

rclib_core_update_play_source ()

gboolean            rclib_core_update_play_source       (RCLibCorePlaySource source_type,
                                                         gpointer source_reference,
                                                         GDestroyNotify notify,
                                                         const gchar *cookie);

Update the source reference.

source_type :

the source type

source_reference :

the source reference. [allow-none]

notify :

the reference destroy notify. [allow-none]

cookie :

he cookie for third-party play item. [allow-none]

Returns :

Whether the source reference updated successfully.

Signal Details

The "balance-changed" signal

void                user_function                      (RCLibCore *core,
                                                        gfloat     balance,
                                                        gpointer   user_data)      : Run First

The ::balance-changed signal is emitted when new balance was applied.

core :

the RCLibCore that received the signal

balance :

the balance value (from -1.0 (left) to 1.0 (right))

user_data :

user data set when the signal handler was connected.

The "buffer-probe" signal

void                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.

core :

the RCLibCore that received the signal

buffer :

the GstBuffer

caps :

the GstCaps

user_data :

user data set when the signal handler was connected.

The "buffering" signal

void                user_function                      (RCLibCore *core,
                                                        gint       percent,
                                                        gpointer   user_data)      : Run First

The ::buffering signal is emitted when the core is buffering.

core :

the RCLibCore that received the signal

percent :

the buffering percent (0-100)

user_data :

user data set when the signal handler was connected.

The "eos" signal

void                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.

core :

the RCLibCore that received the signal

user_data :

user data set when the signal handler was connected.

The "eq-changed" signal

void                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.

core :

the RCLibCore that received the signal

type :

the equalizer style type

values :

an array of 10 gdouble elements for equalizer settings

user_data :

user data set when the signal handler was connected.

The "error" signal

void                user_function                      (RCLibCore *core,
                                                        gchar     *arg1,
                                                        gpointer   user_data)      : Run First

The ::error signal is emitted when any error in the core occurs.

core :

the RCLibCore that received the signal

user_data :

user data set when the signal handler was connected.

The "new-duration" signal

void                user_function                      (RCLibCore *core,
                                                        gint64     duration,
                                                        gpointer   user_data)      : Run First

The ::new-duration signal is emitted when new duration information was found.

core :

the RCLibCore that received the signal

duration :

the duration (unit: nanosecond)

user_data :

user data set when the signal handler was connected.

The "state-changed" signal

void                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.

core :

the RCLibCore that received the signal

state :

the state of the core

user_data :

user data set when the signal handler was connected.

The "tag-found" signal

void                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.

core :

the RCLibCore that received the signal

metadata :

the metadata

uri :

the URI

user_data :

user data set when the signal handler was connected.

The "uri-changed" signal

void                user_function                      (RCLibCore *core,
                                                        gchar     *uri,
                                                        gpointer   user_data)      : Run First

The ::uri-changed signal is emitted when new URI was set.

core :

the RCLibCore that received the signal

uri :

the URI

user_data :

user data set when the signal handler was connected.

The "volume-changed" signal

void                user_function                      (RCLibCore *core,
                                                        gdouble    volume,
                                                        gpointer   user_data)      : Run First

The ::volume-changed signal is emitted when the volume was changed.

core :

the RCLibCore that received the signal

volume :

the volume (from 0.0 to 1.0)

user_data :

user data set when the signal handler was connected.