RBEncoder

RBEncoder — audio transcoder interface

Synopsis

                    RBEncoder;
RBEncoder*          rb_encoder_new                      (void);
gboolean            rb_encoder_encode                   (RBEncoder *encoder,
                                                         RhythmDBEntry *entry,
                                                         const char *dest,
                                                         GList *mime_types);
void                rb_encoder_cancel                   (RBEncoder *encoder);
gboolean            rb_encoder_get_preferred_mimetype   (RBEncoder *encoder,
                                                         GList *mime_types,
                                                         char **mime,
                                                         char **extension);

Object Hierarchy

  GInterface
   +----RBEncoder

Signals

  "completed"                                      : Run Last
  "error"                                          : Run Last
  "progress"                                       : Run Last

Description

The RBEncoder interface provides transcoding between audio formats based on MIME types.

The encoder picks the output format from a list provided by the caller, limited by the available codecs. It operatees asynchronously and provides status updates in the form of signals.

A new encoder instance should be created for each file that is transcoded.

Details

RBEncoder

typedef struct _RBEncoder RBEncoder;


rb_encoder_new ()

RBEncoder*          rb_encoder_new                      (void);

Creates a new RBEncoder instance.

Returns :

the new RBEncoder

rb_encoder_encode ()

gboolean            rb_encoder_encode                   (RBEncoder *encoder,
                                                         RhythmDBEntry *entry,
                                                         const char *dest,
                                                         GList *mime_types);

Initiates encoding. A target MIME type will be selected from the list given. If the source format is in the list, that will be chosen regardless of order. Otherwise, the first type in the list that the encoder can produce will be selected.

Encoding takes places asynchronously. If the return value is TRUE, the caller should wait for a 'completed' or 'error' signal to indicate that it has finished.

encoder :

the RBEncoder

entry :

the RhythmDBEntry to transcode

dest :

destination file URI

mime_types :

a GList of target MIME types in order of preference

Returns :

TRUE if encoding has started

rb_encoder_cancel ()

void                rb_encoder_cancel                   (RBEncoder *encoder);

Attempts to cancel any in progress encoding. The encoder should delete the destination file, if it created one.

encoder :

a RBEncoder

rb_encoder_get_preferred_mimetype ()

gboolean            rb_encoder_get_preferred_mimetype   (RBEncoder *encoder,
                                                         GList *mime_types,
                                                         char **mime,
                                                         char **extension);

Identifies the first MIME type in the list that the encoder can actually encode to. The file extension (eg. '.mp3' for audio/mpeg) associated with the selected type is also returned.

encoder :

a RBEncoder

mime_types :

a GList of MIME type strings in order of preference

mime :

returns the selected MIME type, if any

extension :

returns the file extension associated with the selected MIME type, if any

Returns :

TRUE if a format was identified

Signal Details

The "completed" signal

void                user_function                      (RBEncoder *encoder,
                                                        guint64    arg1,
                                                        gpointer   user_data)      : Run Last

Emitted when the encoding process is complete. The destination file will be closed and flushed to disk when this occurs.

encoder :

the RBEncoder instance

user_data :

user data set when the signal handler was connected.

The "error" signal

void                user_function                      (RBEncoder *encoder,
                                                        gpointer   error,
                                                        gpointer   user_data)      : Run Last

Emitted when an error occurs during encoding.

encoder :

the RBEncoder instance

error :

a GError describing the error

user_data :

user data set when the signal handler was connected.

The "progress" signal

void                user_function                      (RBEncoder *encoder,
                                                        gdouble    fraction,
                                                        gpointer   user_data)      : Run Last

Emitted regularly during the encoding process to provide progress updates.

encoder :

the RBEncoder instance

fraction :

progress as a fraction (0..1)

user_data :

user data set when the signal handler was connected.