## RBEncoder RBEncoder — audio transcoder interface |

## Synopsis

                        RBEncoder;
                        RBEncoderIface;
    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;

### RBEncoderIface

    typedef struct {
    	GTypeInterface g_iface;

    	/* vtable */
    	gboolean (*encode) (RBEncoder *encoder,
    					 RhythmDBEntry *entry,
    					 const char *dest,
    					 GList *mime_types);
    	void		(*cancel) (RBEncoder *encoder);
    	gboolean (*get_preferred_mimetype) (RBEncoder *encoder,
    							 GList *mime_types,
    							 char **mime,
    							 char **extension);

    	/* signals */
    	void (*progress) (RBEncoder *encoder,  double fraction);
    	void (*completed) (RBEncoder *encoder, guint64 dest_size);
    	void (*error) (RBEncoder *encoder, 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,
                                                             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.