RCLibLyric

RCLibLyric — The lyric processor

Synopsis

#include <rclib-lyric.h>

struct              RCLibLyric;
struct              RCLibLyricClass;
struct              RCLibLyricData;
struct              RCLibLyricParsedData;
void                rclib_lyric_clean                   (guint index);
void                rclib_lyric_exit                    ();
const gchar *       rclib_lyric_get_fallback_encoding   ();
GObject *           rclib_lyric_get_instance            ();
const RCLibLyricData * rclib_lyric_get_line             (guint index,
                                                         gint64 time);
GSequenceIter *     rclib_lyric_get_line_iter           (guint index,
                                                         gint64 time);
const RCLibLyricParsedData * rclib_lyric_get_parsed_data
                                                        (guint index);
const gchar *       rclib_lyric_get_search_dir          ();
gint64              rclib_lyric_get_track_time_offset   (guint index);
void                rclib_lyric_init                    ();
gboolean            rclib_lyric_is_available            (guint index);
gboolean            rclib_lyric_load_file               (const gchar *filename,
                                                         guint index);
gchar *             rclib_lyric_search_lyric            (const gchar *uri,
                                                         const gchar *title,
                                                         const gchar *artist);
void                rclib_lyric_set_fallback_encoding   (const gchar *encoding);
void                rclib_lyric_set_search_dir          (const gchar *dir);
gulong              rclib_lyric_signal_connect          (const gchar *name,
                                                         GCallback callback,
                                                         gpointer data);
void                rclib_lyric_signal_disconnect       (gulong handler_id);

Object Hierarchy

  GObject
   +----RCLibLyric

Signals

  "line-changed"                                   : Run First
  "lyric-may-missing"                              : Run First
  "lyric-ready"                                    : Run First
  "lyric-timer"                                    : Run First

Description

The RCLibLyric is a class which processes the lyric data. It can read lyric data from lyric file, and then parse them. It can load two lyric tracks. The timer inside can send signals for lyric display.

Details

struct RCLibLyric

struct RCLibLyric;

The lyric processor. The contents of the RCLibLyric structure are private and should only be accessed via the provided API.


struct RCLibLyricClass

struct RCLibLyricClass {
};

RCLibLyric class.


struct RCLibLyricData

struct RCLibLyricData {
    gint64 time;
    gint64 length;
    gchar *text;
};

The structure for lyric data.

gint64 time;

the time line (unit: nanosecond)

gint64 length;

the length (unit: nanosecond)

gchar *text;

the lyric text

struct RCLibLyricParsedData

struct RCLibLyricParsedData {
    GSequence *seq;
    gchar *filename;
    gchar *title;
    gchar *artist;
    gchar *album;
    gchar *author;
    gint offset;
};

The structure for parsed lyric data.

GSequence *seq;

the GSequence which contains the lyric data

gchar *filename;

the file path of the lyric file

gchar *title;

the title

gchar *artist;

the artist

gchar *album;

the album

gchar *author;

the author of the lyric file

gint offset;

the offset time of the lyric data

rclib_lyric_clean ()

void                rclib_lyric_clean                   (guint index);

Clean the lyric data in the running lyric prcessor instance.

index :

the lyric track index

rclib_lyric_exit ()

void                rclib_lyric_exit                    ();

Unload the lyric process instance.


rclib_lyric_get_fallback_encoding ()

const gchar *       rclib_lyric_get_fallback_encoding   ();

Get the fallback encoding for the lyric parser, NULL if it is no set.

Returns :

The fallback encoding, do not free or modify it.

rclib_lyric_get_instance ()

GObject *           rclib_lyric_get_instance            ();

Get the running RCLibLyric instance.

Returns :

The running instance. [transfer none]

rclib_lyric_get_line ()

const RCLibLyricData * rclib_lyric_get_line             (guint index,
                                                         gint64 time);

Find the lyric line which matches to the given time (in nanoseconds).

time :

the time to search

index :

the lyric track index

Returns :

The matched line data, NULL if not found.

rclib_lyric_get_line_iter ()

GSequenceIter *     rclib_lyric_get_line_iter           (guint index,
                                                         gint64 time);

Find iter of the lyric line which matches to the given time (in nanoseconds).

time :

the time to search

index :

the lyric track index

Returns :

The GSequenceIter of the lyric line, NULL if not found. [transfer none]

rclib_lyric_get_parsed_data ()

const RCLibLyricParsedData * rclib_lyric_get_parsed_data
                                                        (guint index);

Get the parsed lyric data by the given track index.

index :

the lyric track index

Returns :

The parsed lyric data. [transfer none]

rclib_lyric_get_search_dir ()

const gchar *       rclib_lyric_get_search_dir          ();

Get the directory for searching the lyric files.

Returns :

The directory path.

rclib_lyric_get_track_time_offset ()

gint64              rclib_lyric_get_track_time_offset   (guint index);

Get the time offset (in nanosecond) by the given track index

index :

the lyric track index

Returns :

The delay time.

rclib_lyric_init ()

void                rclib_lyric_init                    ();

Initialize the lyric process instance.


rclib_lyric_is_available ()

gboolean            rclib_lyric_is_available            (guint index);

Check whether the lyric in the given track index is available.

index :

the lyric track index

Returns :

Whether the lyric is available.

rclib_lyric_load_file ()

gboolean            rclib_lyric_load_file               (const gchar *filename,
                                                         guint index);

Load lyric file and then parse it.

filename :

the lyric file to load

index :

the lyric track index (0 or 1)

Returns :

Whether the file is loaded and parsed.

rclib_lyric_search_lyric ()

gchar *             rclib_lyric_search_lyric            (const gchar *uri,
                                                         const gchar *title,
                                                         const gchar *artist);

Search the lyric file by given information.

uri :

the URI

title :

the title

artist :

the artist

Returns :

The lyric file path, NULL if not found.

rclib_lyric_set_fallback_encoding ()

void                rclib_lyric_set_fallback_encoding   (const gchar *encoding);

Set the fallback encoding for the lyric parser.

encoding :

the fallback encoding, set to NULL if not used

rclib_lyric_set_search_dir ()

void                rclib_lyric_set_search_dir          (const gchar *dir);

Set the directory for searching the lyric files.

dir :

the directory to set

rclib_lyric_signal_connect ()

gulong              rclib_lyric_signal_connect          (const gchar *name,
                                                         GCallback callback,
                                                         gpointer data);

Connect the GCallback function to the given signal for the running instance of RCLibLyric object.

name :

the name of the signal

callback :

the the GCallback to connect. [scope call]

data :

the user data

Returns :

The handler ID.

rclib_lyric_signal_disconnect ()

void                rclib_lyric_signal_disconnect       (gulong handler_id);

Disconnects a handler from the running RCLibLyric 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

Signal Details

The "line-changed" signal

void                user_function                      (RCLibLyric *lyric,
                                                        guint       index,
                                                        gpointer    lyric_data,
                                                        gint64      offset,
                                                        gpointer    user_data)       : Run First

The ::line-changed signal is emitted when a lyric line has been found which matches the current playing position.

lyric :

the RCLibLyric that received the signal

index :

the track index of the current lyric line

lyric_data :

the lyric data of the current lyric line

offset :

the time offset of the lyric data

user_data :

user data set when the signal handler was connected.

The "lyric-may-missing" signal

void                user_function                      (RCLibLyric *lyric,
                                                        gpointer    user_data)      : Run First

The ::lyric-may-missing signal is emitted if the lyric file of the current playing music may not exist.

lyric :

the RCLibLyric that received the signal

user_data :

user data set when the signal handler was connected.

The "lyric-ready" signal

void                user_function                      (RCLibLyric *lyric,
                                                        guint       index,
                                                        gpointer    user_data)      : Run First

The ::lyric-ready signal is emitted when a lyric track is ready to be used.

lyric :

the RCLibLyric that received the signal

index :

the track index which is ready

user_data :

user data set when the signal handler was connected.

The "lyric-timer" signal

void                user_function                      (RCLibLyric *lyric,
                                                        guint       index,
                                                        gint64      pos,
                                                        gpointer    lyric_data,
                                                        gint64      offset,
                                                        gpointer    user_data)       : Run First

The ::lyric-timer signal is emitted every 100ms, used for lyric display.

lyric :

the RCLibLyric that received the signal

index :

the track index of the current lyric line

pos :

current time position

lyric_data :

the lyric data of the current lyric line

offset :

the time offset of the lyric data

user_data :

user data set when the signal handler was connected.