## RBEncoder RBEncoder — audio transcoder interface |

## Synopsis

    enum                RBEncoderError;
    GQuark              rb_encoder_error_quark              (void);
    struct              RBEncoderIface;
    struct              RBEncoderFactoryClass;
    RBEncoderFactory *  rb_encoder_factory_get              (void);
    RBEncoder *         rb_encoder_new                      (void);
    void                rb_encoder_encode                   (RBEncoder *encoder,
                                                             RhythmDBEntry *entry,
                                                             const char *dest,
                                                             gboolean overwrite,
                                                             GstEncodingProfile *profile);
    void                rb_encoder_cancel                   (RBEncoder *encoder);
    gboolean            rb_encoder_get_missing_plugins      (RBEncoder *encoder,
                                                             GstEncodingProfile *profile,
                                                             char ***details,
                                                             char ***descriptions);

## Description

The RBEncoder interface provides transcoding between audio formats based on encoding profiles. The encoder implementation operates asynchronously and provides status updates in the form of signals emitted on the main thread. A new encoder instance should be created for each file that is transcoded or copied.

## Details

### enum RBEncoderError

    typedef enum {
    	RB_ENCODER_ERROR_FORMAT_UNSUPPORTED,
    	RB_ENCODER_ERROR_INTERNAL,
    	RB_ENCODER_ERROR_FILE_ACCESS,
    	RB_ENCODER_ERROR_OUT_OF_SPACE,
    	RB_ENCODER_ERROR_DEST_READ_ONLY,
    	RB_ENCODER_ERROR_DEST_EXISTS
    } RBEncoderError;

`RB_ENCODER_ERROR_FORMAT_UNSUPPORTED` |
`RB_ENCODER_ERROR_INTERNAL` |
`RB_ENCODER_ERROR_FILE_ACCESS` |
`RB_ENCODER_ERROR_OUT_OF_SPACE` |
`RB_ENCODER_ERROR_DEST_READ_ONLY` |
`RB_ENCODER_ERROR_DEST_EXISTS` |

### rb_encoder_error_quark ()

    GQuark              rb_encoder_error_quark              (void);

### struct RBEncoderIface

    struct RBEncoderIface {
    	GTypeInterface g_iface;

    	/* vtable */
    	void		(*encode) (RBEncoder *encoder,
    					 RhythmDBEntry *entry,
    					 const char *dest,
    					 gboolean overwrite,
    					 GstEncodingProfile *profile);
    	void		(*cancel) (RBEncoder *encoder);
    	gboolean (*get_missing_plugins) (RBEncoder *encoder,
    					 GstEncodingProfile *profile,
    					 char ***details,
    					 char ***descriptions);

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

### struct RBEncoderFactoryClass

    struct RBEncoderFactoryClass {
    	GObjectClass obj_class;

    	/* signals */
    	void (*prepare_source) (RBEncoderFactory *factory, const char *uri, GObject *source);
    	void (*prepare_sink) (RBEncoderFactory *factory, const char *uri, GObject *sink);
    };

### rb_encoder_factory_get ()

    RBEncoderFactory *  rb_encoder_factory_get              (void);

Returns the RBEncoderFactory instance.

Returns : | the RBEncoderFactory. [transfer none]

### rb_encoder_new ()

    RBEncoder *         rb_encoder_new                      (void);

Creates a new RBEncoder instance.

Returns : | the new RBEncoder. [transfer full]

### rb_encoder_encode ()

    void                rb_encoder_encode                   (RBEncoder *encoder,
                                                             RhythmDBEntry *entry,
                                                             const char *dest,
                                                             gboolean overwrite,
                                                             GstEncodingProfile *profile);

Initiates encoding, transcoding to the specified profile if specified.

Encoding and error reporting takes place asynchronously. The caller should wait for the 'completed' signal which indicates it has either completed or failed.

`encoder` : | the RBEncoder
`entry` : | the RhythmDBEntry to transcode
`dest` : | destination file URI
`overwrite` : | if `TRUE`, overwrite `dest` if it already exists
`profile` : | encoding profile to use, or NULL to just copy

### 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_missing_plugins ()

    gboolean            rb_encoder_get_missing_plugins      (RBEncoder *encoder,
                                                             GstEncodingProfile *profile,
                                                             char ***details,
                                                             char ***descriptions);

Retrieves the plugin installer detail strings and descriptions for any missing plugins required to use the specified encoding profile.

`encoder` : | a RBEncoder
`profile` : | an encoding profile
`details` : | returns plugin installer detail strings. [out callee-allocates]
`descriptions` : | returns plugin descriptions. [out callee-allocates]
Returns : | `TRUE` if some detail strings are returned, `FALSE` otherwise