## PtWaveloader

PtWaveloader — Loads the waveform for a given file.

## Stability Level

Unstable, unless otherwise indicated

## Functions

PtWaveloader * | pt_waveloader_new ()
gboolean | pt_waveloader_load_finish ()
void | pt_waveloader_load_async ()
gint64 | pt_waveloader_get_duration ()
PtWavedata * | pt_waveloader_get_data ()

## Properties

gchar * | uri | Read / Write / Construct

## Signals

void | progress | Run First

## Types and Values

struct | PtWaveloader

## Object Hierarchy

        GObject
        ╰── PtWaveloader

## Includes

    #include <parlatype/pt-waveloader.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. | [allow-none]

#### Returns

a new PtWaveloader.

[transfer full]

### pt_waveloader_load_finish ()

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

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

#### Parameters

wl | a PtWaveloader |
result | the GAsyncResult passed to your GAsyncReadyCallback |
error | a pointer to a NULL GError, or NULL. | [allow-none]

#### Returns

TRUE if successful, or FALSE with error set

### pt_waveloader_load_async ()

    void
    pt_waveloader_load_async (PtWaveloader *wl,
                              GCancellable *cancellable,
                              GAsyncReadyCallback callback,
                              gpointer user_data);

Writes the raw sample data to a temporary file and also gets the number of channels, the bit rate and the exact duration. Load only once and on success the data can be retrieved as a PtWavedata. It's a programmer's error trying to retrieve the data without prior loading.

Emits a progress signal while saving the temporary file.

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

#### Parameters

wl | a PtWaveloader |
cancellable | a GCancellable or NULL. | [allow-none]
callback | a GAsyncReadyCallback to call when the operation is complete. | [scope async]
user_data | user_data for callback. | [closure]

### pt_waveloader_get_duration ()

    gint64
    pt_waveloader_get_duration (PtWaveloader *wl);

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

#### Parameters

wl | a PtWaveloader |

#### Returns

duration in nanoseconds as used by GStreamer

### pt_waveloader_get_data ()

    PtWavedata *
    pt_waveloader_get_data (PtWaveloader *wl,
                            gint pps);

Returns wave data needed for visual representation as raw data. The requested resolution is given as pixel per seconds, e.g. 100 means one second is represented by 100 samples, is 100 pixels wide. The returned resolution doesn't have to be necessarily exactly the requested resolution, it might be a bit differnt, depending on the bit rate.

#### Parameters

wl | a PtWaveloader |
pps | the requested pixel per second ratio |

#### Returns

the PtWavedata, after use free with `pt_wavedata_free()`.

[transfer full]

## Types and Values

### struct PtWaveloader

    struct PtWaveloader;

The PtWaveloader contains only private fields and should not be directly accessed.

## Property Details

### The `“uri”` property

      “uri”                      gchar *

URI of the audio file.

Flags: Read / Write / Construct

Default value: ""

## Signal Details

### The `“progress”` signal

    void
    user_function (PtWaveloader *wl,
                   gdouble       progress,
                   gpointer      user_data)

Indicates progress on a scale from 0.0 to 1.0, however it does not emit the value 0.0 nor 1.0. Wait for a successful operation until any gui element showing progress is dismissed.

#### Parameters

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