RBEncoder

RBEncoder — audio transcoder interface

Synopsis

                    RBEncoder;
                    RBEncoderIface;
RBEncoder*          rb_encoder_new                      (void);
gboolean            rb_encoder_encode                   (RBEncoder *encoder,
                                                         RhythmDBEntry *entry,
                                                         const char *dest,
                                                         const char *dest_media_type);
void                rb_encoder_cancel                   (RBEncoder *encoder);
gboolean            rb_encoder_get_media_type           (RBEncoder *encoder,
                                                         RhythmDBEntry *entry,
                                                         GList *dest_media_types,
                                                         char **media_type,
                                                         char **extension);
gboolean            rb_encoder_get_missing_plugins      (RBEncoder *encoder,
                                                         const char *media_type,
                                                         char ***details);

Object Hierarchy

  GInterface
   +----RBEncoder

Signals

  "completed"                                      : Run Last
  "overwrite"                                      : Run Last
  "progress"                                       : Run Last

Description

The RBEncoder interface provides transcoding between audio formats based on media types. Media types are conceptually similar to MIME types, and overlap in many cases, but the media type for an encoding is not always the same as the MIME type for files using that encoding.

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;


RBEncoderIface

typedef struct {
	GTypeInterface g_iface;

	/* vtable */
	gboolean (*encode) (RBEncoder *encoder,
					 RhythmDBEntry *entry,
					 const char *dest,
					 const char *dest_media_type);
	void		(*cancel) (RBEncoder *encoder);
	gboolean (*get_media_type) (RBEncoder *encoder,
					 RhythmDBEntry *entry,
					 GList *dest_media_types,
					 char **media_type,
					 char **extension);
	gboolean (*get_missing_plugins) (RBEncoder *encoder,
					 const char *media_type,
					 char ***details);

	/* signals */
	void (*progress) (RBEncoder *encoder,  double fraction);
	gboolean (*overwrite) (RBEncoder *encoder, GFile *file);
	void (*completed) (RBEncoder *encoder, guint64 dest_size, const char *mediatype, GError *error);
} RBEncoderIface;


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,
                                                         const char *dest_media_type);

Initiates encoding, transcoding to the specified media type if it doesn't match the current media type of the entry. The caller should use rb_encoder_get_media_type to select a destination media type.

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

encoder :

the RBEncoder

entry :

the RhythmDBEntry to transcode

dest :

destination file URI

dest_media_type :

destination media type, or NULL to just copy it

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, and emit the 'completed' signal.

encoder :

a RBEncoder

rb_encoder_get_media_type ()

gboolean            rb_encoder_get_media_type           (RBEncoder *encoder,
                                                         RhythmDBEntry *entry,
                                                         GList *dest_media_types,
                                                         char **media_type,
                                                         char **extension);

Identifies the first media 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

entry :

the source RhythmDBEntry

dest_media_types :

a GList of media type strings in order of preference

media_type :

returns the selected media type, if any

extension :

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

Returns :

TRUE if a format was identified

rb_encoder_get_missing_plugins ()

gboolean            rb_encoder_get_missing_plugins      (RBEncoder *encoder,
                                                         const char *media_type,
                                                         char ***details);

Retrieves the plugin installer detail strings for any missing plugins required to encode the specified media type.

encoder :

a RBEncoder

media_type :

the media type required

details :

returns plugin installer detail strings

Returns :

TRUE if some detail strings are returned, FALSE otherwise

Signal Details

The "completed" signal

void                user_function                      (RBEncoder *encoder,
                                                        guint64    dest_size,
                                                        gchar     *mediatype,
                                                        gpointer   error,
                                                        gpointer   user_data)      : Run Last

Emitted when the encoding process is complete, or when a fatal error has occurred. The destination file, if one exists, will be closed and flushed to disk before this signal is emitted.

encoder :

the RBEncoder instance

dest_size :

size of the output file

mediatype :

output media type

error :

encoding error, or NULL if successful

user_data :

user data set when the signal handler was connected.

The "overwrite" signal

gboolean            user_function                      (RBEncoder *encoder,
                                                        GObject   *file,
                                                        gpointer   user_data)      : Run Last

Emitted when a destination file already exists. If the return value if TRUE, the file will be overwritten, otherwise the transfer will be aborted.

encoder :

the RBEncoder instance

file :

the GFile that may be overwritten

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.