## IpatchSampleList IpatchSampleList — Sample list data types and functions |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchSampleList;
                        IpatchSampleListItem;
    #define             IPATCH_TYPE_SAMPLE_LIST
    GType               ipatch_sample_list_get_type         (void);
    IpatchSampleList *  ipatch_sample_list_new              (void);
    void                ipatch_sample_list_free             (IpatchSampleList *list);
    IpatchSampleList *  ipatch_sample_list_duplicate        (IpatchSampleList *list);
    IpatchSampleListItem * ipatch_sample_list_item_new      (void);
    IpatchSampleListItem * ipatch_sample_list_item_new_init (IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);
    void                ipatch_sample_list_item_free        (IpatchSampleListItem *item);
    IpatchSampleListItem * ipatch_sample_list_item_duplicate
                                                            (IpatchSampleListItem *item);
    void                ipatch_sample_list_append           (IpatchSampleList *list,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);
    void                ipatch_sample_list_prepend          (IpatchSampleList *list,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);
    void                ipatch_sample_list_insert_index     (IpatchSampleList *list,
                                                             guint index,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);
    void                ipatch_sample_list_insert           (IpatchSampleList *list,
                                                             guint pos,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);
    void                ipatch_sample_list_cut              (IpatchSampleList *list,
                                                             guint pos,
                                                             guint size);
    gboolean            ipatch_sample_list_render           (IpatchSampleList *list,
                                                             gpointer buf,
                                                             guint pos,
                                                             guint size,
                                                             int format,
                                                             GError **err);

## Description

Sample lists define audio data from concatenated segments of other audio sources. The lists are always mono (a single channel can be selected from multi-channel sources). Multi-channel audio can be created from combining multiple sample lists of the same length.

## Details

### IpatchSampleList

    typedef struct {
      GList *items;			/* list of IpatchSampleListItem structs */
      guint total_size;		/* total size of audio data in frames */
    } IpatchSampleList;

A sample edit list. Allows for non-destructive sample editing by defining new audio samples from one or more audio sample segments.

### IpatchSampleListItem

    typedef struct {
      IpatchSample *sample;	        /* Sample for this segment */
      guint ofs;                    /* Offset in sample of segment start */
      guint size;			/* Size in frames of audio segment */
      guint32 channel : 3;          /* Channel to use in sample */
      guint32 reserved : 29;
    } IpatchSampleListItem;

Defines an audio segment in a IpatchSampleList.

### IPATCH_TYPE_SAMPLE_LIST

    #define IPATCH_TYPE_SAMPLE_LIST   (ipatch_sample_list_get_type ())

### ipatch_sample_list_get_type ()

    GType               ipatch_sample_list_get_type         (void);

### ipatch_sample_list_new ()

    IpatchSampleList *  ipatch_sample_list_new              (void);

Creates a new empty (zero item terminated) sample list.

Returns : | Newly allocated empty sample list.

### ipatch_sample_list_free ()

    void                ipatch_sample_list_free             (IpatchSampleList *list);

Free a sample list.

`list` : | Sample list to free

### ipatch_sample_list_duplicate ()

    IpatchSampleList *  ipatch_sample_list_duplicate        (IpatchSampleList *list);

Duplicate a sample list.

`list` : | Sample list to duplicate
Returns : | Newly allocated duplicate of `list`.

### ipatch_sample_list_item_new ()

    IpatchSampleListItem * ipatch_sample_list_item_new      (void);

Create a new node for a sample list.

Returns : | Newly allocated list node which should be freed with `ipatch_sample_list_item_free()` when finished using it.

### ipatch_sample_list_item_new_init ()

    IpatchSampleListItem * ipatch_sample_list_item_new_init (IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);

Create a new sample list item and initialize it with the provided parameters.

`sample` : | Sample containing audio for the segment
`ofs` : | Offset in `sample` of audio segment
`size` : | Size of audio segment in frames
`channel` : | Channel to use from `sample`
Returns : | Newly allocated sample list item which should be freed with `ipatch_sample_list_item_free()` when done with it.

### ipatch_sample_list_item_free ()

    void                ipatch_sample_list_item_free        (IpatchSampleListItem *item);

Free a sample list item previously allocated by `ipatch_sample_list_item_new()`.

`item` : | Sample list item to free

### ipatch_sample_list_item_duplicate ()

    IpatchSampleListItem * ipatch_sample_list_item_duplicate
                                                            (IpatchSampleListItem *item);

Duplicate a sample list item node.

`item` : | Sample list item to duplicate
Returns : | New duplicate sample list item.

### ipatch_sample_list_append ()

    void                ipatch_sample_list_append           (IpatchSampleList *list,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);

Append an audio segment to a sample list.

`list` : | Sample list
`sample` : | Sample containing audio segment to append
`ofs` : | Offset in `sample` of beginning of audio segment (in frames)
`size` : | Number of frames of audio segment to append
`channel` : | Channel to use from `sample`

### ipatch_sample_list_prepend ()

    void                ipatch_sample_list_prepend          (IpatchSampleList *list,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);

Prepend an audio segment to a sample list.

`list` : | Sample list
`sample` : | Sample containing audio segment to prepend
`ofs` : | Offset in `sample` of beginning of audio segment (in frames)
`size` : | Number of frames of audio segment to prepend
`channel` : | Channel to use from `sample`

### ipatch_sample_list_insert_index ()

    void                ipatch_sample_list_insert_index     (IpatchSampleList *list,
                                                             guint index,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);

Insert an audio segment into a sample list before a given list segment `index`.

`list` : | Sample list
`index` : | List index to insert segment before (0 = prepend, -1 = append)
`sample` : | Sample containing audio segment to insert
`ofs` : | Offset in `sample` of beginning of audio segment (in frames)
`size` : | Number of frames of audio segment to insert
`channel` : | Channel to use from `sample`

### ipatch_sample_list_insert ()

    void                ipatch_sample_list_insert           (IpatchSampleList *list,
                                                             guint pos,
                                                             IpatchSample *sample,
                                                             guint ofs,
                                                             guint size,
                                                             guint channel);

Insert an audio segment into a sample list at a given sample position in frames (`pos`). Existing segments will be split as needed to accomodate the inserted segment.

`list` : | Sample list
`pos` : | Position in audio data in frames to insert segment at
`sample` : | Sample containing audio segment to insert
`ofs` : | Offset in `sample` of beginning of audio segment (in frames)
`size` : | Number of frames of audio segment to insert
`channel` : | Channel to use from `sample`

### ipatch_sample_list_cut ()

    void                ipatch_sample_list_cut              (IpatchSampleList *list,
                                                             guint pos,
                                                             guint size);

Cut a segment of audio from a sample list.

`list` : | Sample list
`pos` : | Start position of sample data to cut, in frames
`size` : | Size of area to cut, in frames

### ipatch_sample_list_render ()

    gboolean            ipatch_sample_list_render           (IpatchSampleList *list,
                                                             gpointer buf,
                                                             guint pos,
                                                             guint size,
                                                             int format,
                                                             GError **err);

Copies sample data from a sample list, converting as necessary and storing to `buf`.

`list` : | Sample list
`buf` : | Buffer to store the rendered audio to (should be `size` * bytes_per_frame)
`pos` : | Position in sample list audio to start from, in frames
`size` : | Size of sample data to render in frames
`format` : | Sample format to render to (must be mono)
`err` : | Location to store error to or `NULL` to ignore