## PtWaveloader

PtWaveloader — Loads the waveform for a given file.

## Stability Level

Stable, unless otherwise indicated

## Functions

PtWaveloader * | pt_waveloader_new ()
void | pt_waveloader_load_async ()
gboolean | pt_waveloader_load_finish ()
void | pt_waveloader_resize_async ()
gboolean | pt_waveloader_resize_finish ()
gboolean | pt_waveloader_resize ()
gint64 | pt_waveloader_get_duration ()
GArray * | pt_waveloader_get_data ()

## Properties

char * | uri | Read / Write / Construct

## Signals

void | array-size-changed | Run First
void | progress | Run First

## Object Hierarchy

        GObject
        ╰── PtWaveloader

## Includes

    #include <parlatype/parlatype.h>

## Description

An object to load waveform data from an audio file. The raw data can be used by a widget to visually represent a waveform.

## Functions

### pt_waveloader_new ()

    PtWaveloader *
    pt_waveloader_new (gchar *uri);

Returns a new PtWaveloader. The `uri` is not checked on construction, but calling `pt_waveloader_load_async()` will fail with an error message.

After use `g_object_unref()` it.

#### Parameters

uri | URI of the audio file to load. | [nullable]

#### Returns

a new PtWaveloader.

[transfer full]

Since: 1.4

### pt_waveloader_load_async ()

    void
    pt_waveloader_load_async (PtWaveloader *self,
                              gint pps,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Saves sample data to private memory. To keep the memory footprint low, the raw data is downsampled to 8000 samples per second (16 bit per sample). This requires approx. 1 MB of memory per minute.

“uri” must be set. If it is not valid, an error will be returned. If there is another load operation going on, an error will be returned.

While saving data “progress” is emitted every 30 ms.

In your callback call pt_waveloader_load_finish to get the result of the operation.

You can get a pointer to the GArray holding the data with pt_waveloader_get_data either before loading it or afterwards.

#### Parameters

self | a PtWaveloader |
pps | pixels per second |
cancellable | a GCancellable or NULL. | [nullable]
callback | a GAsyncReadyCallback to call when the operation is complete. | [scope async][closure user_data]
user_data | user_data for `callback` |

Since: 2.0

### pt_waveloader_load_finish ()

    gboolean
    pt_waveloader_load_finish (PtWaveloader *self,
                               GAsyncResult *result,
                               GError **error);

Gives the result of the async load operation. A cancelled operation results in an error, too.

#### Parameters

self | a PtWaveloader |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a NULL GError, or NULL. | [nullable]

#### Returns

TRUE if successful, or FALSE with error set

Since: 1.4

### pt_waveloader_resize_async ()

    void
    pt_waveloader_resize_async (PtWaveloader *self,
                                gint pps,
                                GCancellable *cancellable,
                                GAsyncReadyCallback callback,
                                gpointer user_data);

Resizes wave form data at the requested resolution `pps` . If the array's size has to be changed, “array-size-changed” is emitted. Any data in the array will be overwritten.

The resolution is given as pixel per seconds, e.g. 100 means one second is represented by 100 samples, is 100 pixels wide. `pps` must be >= 25 and <= 200.

You should have loaded a file with pt_waveloader_load_async before resizing it. There are no concurrent operations allowed. An error is returned, if the file was not loaded before, if it is still loading or if there is another pt_waveloader_get_data_async operation going on.

Cancelling the operation returns an error and lets the array in an inconsistent state. Its size will be according to the requested new resolution, but the data will be partly old, partly new.

In your callback call pt_waveloader_get_data_finish to get the result of the operation.

#### Parameters

self | a PtWaveloader |
pps | the requested pixel per second ratio |
cancellable | a GCancellable or NULL. | [nullable]
callback | a GAsyncReadyCallback to call when the operation is complete. | [scope async][closure user_data]
user_data | user_data for `callback` |

Since: 2.0

### pt_waveloader_resize_finish ()

    gboolean
    pt_waveloader_resize_finish (PtWaveloader *self,
                                 GAsyncResult *result,
                                 GError **error);

Gives the result of the async resize operation. A cancelled operation results in an error, too.

#### Parameters

self | a PtWaveloader |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a NULL GError, or NULL. | [nullable]

#### Returns

TRUE if successful, or FALSE with error set

Since: 2.0

### pt_waveloader_resize ()

    gboolean
    pt_waveloader_resize (PtWaveloader *self,
                          gint pps,
                          GError **error);

Sync version of pt_waveloader_resize_async.

#### Parameters

self | a PtWaveloader |
pps | the requested pixel per second ratio |
error | return location for an error, or NULL. | [nullable]

#### Returns

TRUE if successful, or FALSE with error set

Since: 2.0

### pt_waveloader_get_duration ()

    gint64
    pt_waveloader_get_duration (PtWaveloader *self);

Returns the duration of stream. As the whole stream is scanned, this is supposed to be an exact duration, not an estimate.

#### Parameters

self | a PtWaveloader |

#### Returns

duration in nanoseconds as used by GStreamer

Since: 1.4

### pt_waveloader_get_data ()

    GArray *
    pt_waveloader_get_data (PtWaveloader *self);

This returns the pointer to a GArray that is holding all the wave form data. It consists of a minimum value in the range of -1 to 0 and a maximum value in the range of 0 to 1, repeating this until the end. Each min/max pair can be drawn by the application as one vertical line in the wave form.

Don't modify the data.

#### Parameters

self | a PtWaveloader |

#### Returns

a GArray with wave data.

[element-type float][transfer none]

Since: 2.0

## Property Details

### The `“uri”` property

      “uri”                      char *

URI of the audio file.

Owner: PtWaveloader

Flags: Read / Write / Construct

Default value: ""

## Signal Details

### The `“array-size-changed”` signal

    void
    user_function (PtWaveloader *self,
                   gpointer      user_data)

The size of the array with waveform data has changed.

#### Parameters

self | the waveloader emitting the signal |
user_data | user data set when the signal handler was connected. |

Flags: Run First

### The `“progress”` signal

    void
    user_function (PtWaveloader *self,
                   double        progress,
                   gpointer      user_data)

While loading a waveform a progress signal is emitted, starting with a value greater than 0.0. At the end of the operation, 1.0 is emitted in case of success, otherwise 0.0.

#### Parameters

self | the waveloader emitting the signal |
progress | the new progress state, ranging from 0.0 to 1.0 |
user_data | user data set when the signal handler was connected. |

Flags: Run First