IpatchCramEncoder

IpatchCramEncoder — CRAM encoder object.

Synopsis




                    IpatchCramEncoder;
                    IpatchCramEncoderClass;
enum                IpatchCramEncoderFlags;
IpatchCramEncoder*  ipatch_cram_encoder_new             (IpatchFile *file);
void                ipatch_cram_encoder_set_file        (IpatchCramEncoder *encoder,
                                                         IpatchFile *file);
void                ipatch_cram_encoder_set_audio_endian
                                                        (IpatchCramEncoder *encoder,
                                                         gboolean big_endian);
gboolean            ipatch_cram_encoder_start           (IpatchCramEncoder *encoder,
                                                         GError **err);
gboolean            ipatch_cram_encoder_end             (IpatchCramEncoder *encoder,
                                                         GError **err);
IpatchCramEncoderStats* ipatch_cram_encoder_get_stats   (IpatchCramEncoder *encoder,
                                                         int *count);
gboolean            ipatch_cram_encoder_declare_file    (IpatchCramEncoder *encoder,
                                                         const char *filepath,
                                                         guint64 size,
                                                         guint32 datetime,
                                                         GError **err);
void                ipatch_cram_encoder_declare_binary  (IpatchCramEncoder *encoder,
                                                         guint64 length);
void                ipatch_cram_encoder_declare_flac_audio
                                                        (IpatchCramEncoder *encoder,
                                                         guint64 frames,
                                                         guint width,
                                                         guint channels,
                                                         guint sample_rate,
                                                         guint flags,
                                                         guint64 *offsets);
gboolean            ipatch_cram_encoder_store_binary    (IpatchCramEncoder *encoder,
                                                         gpointer data,
                                                         guint length,
                                                         GError **err);
gboolean            ipatch_cram_encoder_store_audio     (IpatchCramEncoder *encoder,
                                                         const gpointer bufs[],
                                                         guint frames,
                                                         GError **err);
gboolean            ipatch_cram_encoder_store_audio_interleaved
                                                        (IpatchCramEncoder *encoder,
                                                         gconstpointer buf,
                                                         guint frames,
                                                         GError **err);

Object Hierarchy


  GObject
   +----IpatchCramEncoder

Properties


  "adaptive-mid-side"        gboolean              : Read / Write
  "block-size"               gint                  : Read / Write
  "comment"                  gchararray            : Read / Write
  "exhaustive-model-search"  gboolean              : Read / Write
  "max-lpc-order"            gint                  : Read / Write
  "max-rice-partition-order" gint                  : Read / Write
  "min-rice-partition-order" gint                  : Read / Write
  "qlp-coeff-precision"      gint                  : Read / Write
  "qlp-coeff-search"         gboolean              : Read / Write

Description

An object for encoding (compressing) a CRAM file. The IpatchConverter interface may be a more convenient method for encoding a CRAM file.

Details

IpatchCramEncoder

typedef struct {
  guint8 binary_md5[16];    /* final MD5 sum of uncompressed binary */
  guint8 audio_md5[16];	     /* final MD5 sum of uncompressed audio */
  guint64 compress_binary_size;	/* total compressed binary data size */
  guint64 original_size;	/* original file size */
  guint64 total_size;	      /* total size of Cram compressed file */

  /* binary compression parameters */
  int compress_level; /* binary compression level (0-9, -1 = default) */

  /* FLAC audio compression parameters */
  gboolean adaptive_mid_side_coding; /* T:adaptive, F:exhaustive, def:F */
  int block_size;		/* FLAC block size, def:4608 */
  int max_lpc_order;	  /* max LPC order 0-12, 0:only fixed, def:8 */
  int min_rice_partition_order;
  int max_rice_partition_order;
  int qlp_coeff_precision;	/* 0=pick based on blocksize */
  gboolean qlp_coeff_search; /* T:search neighboring coeff, F:fixed */
  gboolean exhaustive_model_search;
} IpatchCramEncoder;


IpatchCramEncoderClass

typedef struct {
  GObjectClass parent_class;
} IpatchCramEncoderClass;


enum IpatchCramEncoderFlags

typedef enum  /*< flags >*/
{
  /* audio is split into separate channels (non-interleaved) */
  IPATCH_CRAM_ENCODER_FLAG_SPLIT_AUDIO = 1 << 0,
  IPATCH_CRAM_ENCODER_FLAG_UNSIGNED_AUDIO = 1 << 1 /* audio is unsigned */
} IpatchCramEncoderFlags;


ipatch_cram_encoder_new ()

IpatchCramEncoder*  ipatch_cram_encoder_new             (IpatchFile *file);

Create a new Cram encoder instance.

file : File to save to or NULL to set later
Returns : New Cram encoder with a refcount of 1 which the caller owns.

ipatch_cram_encoder_set_file ()

void                ipatch_cram_encoder_set_file        (IpatchCramEncoder *encoder,
                                                         IpatchFile *file);

Set the file object to save Cram compressed file to. Either passing a file object to ipatch_cram_encoder_new() or calling this function is required before saving can commence.

encoder : Cram encoder
file : File object

ipatch_cram_encoder_set_audio_endian ()

void                ipatch_cram_encoder_set_audio_endian
                                                        (IpatchCramEncoder *encoder,
                                                         gboolean big_endian);

Set the endianness of the original audio that gets encoded to the Cram file.

encoder : Cram encoder
big_endian : Set to TRUE for big endian audio, FALSE otherwise

ipatch_cram_encoder_start ()

gboolean            ipatch_cram_encoder_start           (IpatchCramEncoder *encoder,
                                                         GError **err);

Should be called before storing any data to a Cram file. Writes Cram headers and gets ready to encode binary and/or audio data.

encoder : Cram encoder
err : Location to store error info or NULL
Returns : TRUE on success, FALSE otherwise

ipatch_cram_encoder_end ()

gboolean            ipatch_cram_encoder_end             (IpatchCramEncoder *encoder,
                                                         GError **err);

Should be called after storing all binary and audio data to a Cram file. Flushes any remaining compressor output and stores last compressed relocation/parameter table.

encoder : Cram encoder
err : Location to store error info or NULL
Returns : TRUE on success (means the Cram file was successfully stored), FALSE otherwise (in which case err may be set).

ipatch_cram_encoder_get_stats ()

IpatchCramEncoderStats* ipatch_cram_encoder_get_stats   (IpatchCramEncoder *encoder,
                                                         int *count);

Get statistics about a encoding session. This function can only be called after the encoding is finished (ipatch_cram_encoder_end()).

encoder : Cram encoder
count : Pointer to an integer to store number of valid entries in returned array (not including termination entry) or NULL to ignore
Returns : A newly allocated array of statistic entries, one for each entry in the Cram relocation table. The array is terminated with an entry with 0 length. Free the array when finished with it.

ipatch_cram_encoder_declare_file ()

gboolean            ipatch_cram_encoder_declare_file    (IpatchCramEncoder *encoder,
                                                         const char *filepath,
                                                         guint64 size,
                                                         guint32 datetime,
                                                         GError **err);

Declare the start of a new file to encode. A call to this function is required for each file that is encoded.

encoder : Cram encoder
filepath : Relative path and file name of file (usually just a file name). Can be NULL in which case the cram file name will be used (no more than 1 file should be stored then).
size : Uncompressed size of the file
datetime : Unix time stamp of the file (or 0 to not store date-time)
err : Location to store error info or NULL to ignore
Returns : TRUE on success, FALSE otherwise

ipatch_cram_encoder_declare_binary ()

void                ipatch_cram_encoder_declare_binary  (IpatchCramEncoder *encoder,
                                                         guint64 length);

Declares a binary segment in the Cram stream. Calls to ipatch_cram_encoder_store_binary() should follow until length bytes have been encoded.

encoder : Cram encoder
length : Length of binary segment to declare

ipatch_cram_encoder_declare_flac_audio ()

void                ipatch_cram_encoder_declare_flac_audio
                                                        (IpatchCramEncoder *encoder,
                                                         guint64 frames,
                                                         guint width,
                                                         guint channels,
                                                         guint sample_rate,
                                                         guint flags,
                                                         guint64 *offsets);

Declares an audio sample for encoding with FLAC at the current position in the stream. For separated multi-channel audio the first channel resides at the current position and the offsets are used to locate the other channels. Calls to ipatch_cram_encoder_store_flac_audio() or ipatch_cram_encoder_store_flac_audio_interleaved() should follow until all audio frames have been encoded.

encoder : Cram encoder
frames : Number of audio frames (i.e., 1 stereo frame is 2 samples)
width : Audio bit width (currently 8, 16 or 24 are valid)
channels : Number of channels (currently only 1 or 2 is valid)
sample_rate : Sample rate of this sample (used for optimization only, can be 0 if unknown which will cause default optimization settings to be used)
flags : Flags, IPATCH_CRAM_ENCODER_FLAG_SPLIT_AUDIO indicates audio is multi-channel and non-interleaved (1 segment for each channel, if this flag is set offsets should also be set) and IPATCH_CRAM_ENCODER_FLAG_UNSIGNED_AUDIO indicates audio is unsigned.
offsets : Only used for split (non-interleaved) multi-channel data. A pointer to an array that specifies file offsets (in the original file) for every channel except the first (so only 1 array index is supported currently). Offsets are from the end of the previous channel and are in bytes.

ipatch_cram_encoder_store_binary ()

gboolean            ipatch_cram_encoder_store_binary    (IpatchCramEncoder *encoder,
                                                         gpointer data,
                                                         guint length,
                                                         GError **err);

Compress and store a chunk of binary data to a Cram file. A call to ipatch_cram_encoder_declare_binary() must be made before encoding any binary data, at which point this function can be called multiple times until the number of declared bytes have been encoded.

encoder : Cram encoder
data : Buffer containing binary data
length : Length of data in buf
err : Location to store error info or NULL
Returns : TRUE on success, FALSE on error (in which case err may be set).

ipatch_cram_encoder_store_audio ()

gboolean            ipatch_cram_encoder_store_audio     (IpatchCramEncoder *encoder,
                                                         const gpointer bufs[],
                                                         guint frames,
                                                         GError **err);

Compress and store a chunk of audio data to a Cram file. A call to ipatch_cram_encoder_declare_flac_audio() must be made before encoding each audio sample, at which point this function can be called multiple times until all the declared audio frames for this sample have been encoded.

encoder : Cram encoder
bufs : An array of pointers that point to each channel of audio, each of frames length samples and with the sample format previously declared with ipatch_cram_encoder_declare_flac_audio().
frames : Number of audio frames to process
err : Location to store error info or NULL
Returns : TRUE on success, FALSE otherwise (in which case err may be set).

ipatch_cram_encoder_store_audio_interleaved ()

gboolean            ipatch_cram_encoder_store_audio_interleaved
                                                        (IpatchCramEncoder *encoder,
                                                         gconstpointer buf,
                                                         guint frames,
                                                         GError **err);

Compress and store a chunk of audio data to a Cram file. A call to ipatch_cram_encoder_declare_flac_audio() must be made before encoding each audio sample, at which point this function can be called multiple times until all the declared audio frames for this sample have been encoded. This function differs from ipatch_cram_encoder_store_audio() in that it consumes channel interleaved audio data instead of channel separated data (provides some convenience to the caller).

encoder : Cram encoder
buf : Sample data (channel interleaved for multi-channel data).
frames : Number of audio frames to process
err : Location to store error info or NULL
Returns : TRUE on success, FALSE otherwise (in which case err may be set).

Property Details

The "adaptive-mid-side" property

  "adaptive-mid-side"        gboolean              : Read / Write

FLAC adaptive mid side encoding.

Default value: FALSE


The "block-size" property

  "block-size"               gint                  : Read / Write

FLAC block size.

Allowed values: [256,16384]

Default value: 4608


The "comment" property

  "comment"                  gchararray            : Read / Write

Comment.

Default value: NULL


The "exhaustive-model-search" property

  "exhaustive-model-search"  gboolean              : Read / Write

FLAC exhaustive model search.

Default value: FALSE


The "max-lpc-order" property

  "max-lpc-order"            gint                  : Read / Write

FLAC max LPC order.

Allowed values: [0,16]

Default value: 8


The "max-rice-partition-order" property

  "max-rice-partition-order" gint                  : Read / Write

FLAC max rice partition order.

Allowed values: [0,8]

Default value: 3


The "min-rice-partition-order" property

  "min-rice-partition-order" gint                  : Read / Write

FLAC min rice partition order.

Allowed values: [0,8]

Default value: 3


The "qlp-coeff-precision" property

  "qlp-coeff-precision"      gint                  : Read / Write

FLAC QLP coeffecient precision.

Allowed values: [0,31]

Default value: 0


The "qlp-coeff-search" property

  "qlp-coeff-search"         gboolean              : Read / Write

FLAC QLP coefficient search.

Default value: FALSE

See Also

IpatchCramEncoderConverter