## RBEncoder RBEncoder — audio transcoder interface |

## Synopsis

                        RBEncoder;
    struct              RBEncoderIface;
    RBEncoder *         rb_encoder_new                      (void);
    void                rb_encoder_encode                   (RBEncoder *encoder,
                                                             RhythmDBEntry *entry,
                                                             const char *dest,
                                                             GstEncodingProfile *profile);
    void                rb_encoder_cancel                   (RBEncoder *encoder);
    gboolean            rb_encoder_get_missing_plugins      (RBEncoder *encoder,
                                                             GstEncodingProfile *profile,
                                                             char ***details,
                                                             char ***descriptions);

## 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 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

### RBEncoder

    typedef struct _RBEncoder RBEncoder;

### struct RBEncoderIface

    struct RBEncoderIface {
    	GTypeInterface g_iface;

    	/* vtable */
    	void		(*encode) (RBEncoder *encoder,
    					 RhythmDBEntry *entry,
    					 const char *dest,
    					 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);
    	gboolean (*overwrite) (RBEncoder *encoder, GFile *file);
    	void (*completed) (RBEncoder *encoder, guint64 dest_size, const char *mediatype, GError *error);
    };

### 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,
                                                             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
`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

## 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.