## AgsWave

AgsWave — Wave class supporting selection and clipboard

## Stability Level

Stable, unless otherwise indicated

## Functions

#define | AGS_WAVE_GET_OBJ_MUTEX()
GRecMutex * | ags_wave_get_obj_mutex ()
gboolean | ags_wave_test_flags ()
void | ags_wave_set_flags ()
void | ags_wave_unset_flags ()
GList * | ags_wave_find_near_timestamp ()
gint | ags_wave_sort_func ()
GObject * | ags_wave_get_audio ()
void | ags_wave_set_audio ()
guint | ags_wave_get_line ()
void | ags_wave_set_line ()
guint | ags_wave_get_samplerate ()
void | ags_wave_set_samplerate ()
guint | ags_wave_get_buffer_size ()
void | ags_wave_set_buffer_size ()
AgsSoundcardFormat | ags_wave_get_format ()
void | ags_wave_set_format ()
AgsTimestamp * | ags_wave_get_timestamp ()
void | ags_wave_set_timestamp ()
GList * | ags_wave_get_buffer ()
void | ags_wave_set_buffer ()
GList * | ags_wave_add ()
void | ags_wave_add_buffer ()
void | ags_wave_remove_buffer ()
GList * | ags_wave_get_selection ()
gboolean | ags_wave_is_buffer_selected ()
AgsBuffer * | ags_wave_find_point ()
AgsBuffer * | ags_wave_find_exact_point ()
GList * | ags_wave_find_region ()
void | ags_wave_free_selection ()
void | ags_wave_free_all_selection ()
void | ags_wave_add_region_to_selection ()
void | ags_wave_remove_region_from_selection ()
void | ags_wave_add_all_to_selection ()
xmlNode * | ags_wave_copy_selection ()
xmlNode * | ags_wave_cut_selection ()
gchar * | ags_wave_copy_selection_as_base64 ()
gchar * | ags_wave_cut_selection_as_base64 ()
void | ags_wave_insert_from_clipboard ()
void | ags_wave_insert_from_clipboard_extended ()
void | ags_wave_insert_base64_from_clipboard ()
void | ags_wave_insert_base64_from_clipboard_extended ()
AgsWave * | ags_wave_new ()

## Properties

AgsAudio * | audio | Read / Write
gpointer | buffer | Read / Write
guint | buffer-size | Read / Write
guint | format | Read / Write
guint | line | Read / Write
guint | samplerate | Read / Write
AgsTimestamp * | timestamp | Read / Write

## Types and Values

#define | AGS_WAVE_DEFAULT_BPM
#define | AGS_WAVE_TICS_PER_BEAT
#define | AGS_WAVE_MINIMUM_BUFFER_LENGTH
#define | AGS_WAVE_DEFAULT_BUFFER_LENGTH
#define | AGS_WAVE_DEFAULT_LENGTH
#define | AGS_WAVE_DEFAULT_JIFFIE
#define | AGS_WAVE_DEFAULT_DURATION
#define | AGS_WAVE_DEFAULT_OFFSET
#define | AGS_WAVE_CLIPBOARD_VERSION
#define | AGS_WAVE_CLIPBOARD_TYPE
#define | AGS_WAVE_CLIPBOARD_FORMAT
#define | AGS_WAVE_CLIPBOARD_XML_TYPE
#define | AGS_WAVE_CLIPBOARD_BASE64_TYPE
#define | AGS_WAVE_CLIPBOARD_MAX_SIZE
enum | AgsWaveFlags

## Object Hierarchy

        GFlags
        ╰── AgsWaveFlags
        GObject
        ╰── AgsWave

## Includes

    #include <ags/audio/ags_wave.h>

## Description

AgsWave acts as a container of AgsBuffer. The `timestamp` property tells the engine what the first x offset of AgsBuffer applies.

You can lookup AgsBuffer by start x offet with `ags_wave_find_near_timestamp()`. The next x offset is calculated as following:

next_x_offset = x_offset + relative_offset;

The relative_offset is calculated as following:

relative_offset = AGS_WAVE_DEFAULT_BUFFER_LENGTH * samplerate;

Use `ags_wave_add_buffer()` to add AgsBuffer to AgsWave and `ags_wave_remove_buffer()` to remove it again.

In order to copy or cut accelerations you select them first by calling `ags_wave_add_region_to_selection()`.

## Functions

### AGS_WAVE_GET_OBJ_MUTEX()

    #define AGS_WAVE_GET_OBJ_MUTEX(obj) (&(((AgsWave *) obj)->obj_mutex))

### ags_wave_get_obj_mutex ()

    GRecMutex *
    ags_wave_get_obj_mutex (AgsWave *wave);

Get object mutex.

#### Parameters

wave | the AgsWave |

#### Returns

the GRecMutex to lock `wave`

Since: 3.1.0

### ags_wave_test_flags ()

    gboolean
    ags_wave_test_flags (AgsWave *wave,
                         AgsWaveFlags flags);

Test `flags` to be set on `wave` .

#### Parameters

wave | the AgsWave |
flags | the flags |

#### Returns

`TRUE` if flags are set, else `FALSE`

Since: 3.0.0

### ags_wave_set_flags ()

    void
    ags_wave_set_flags (AgsWave *wave,
                        AgsWaveFlags flags);

Set `flags` on `wave` .

#### Parameters

wave | the AgsWave |
flags | the flags |

Since: 3.0.0

### ags_wave_unset_flags ()

    void
    ags_wave_unset_flags (AgsWave *wave,
                          AgsWaveFlags flags);

Unset `flags` on `wave` .

#### Parameters

wave | the AgsWave |
flags | the flags |

Since: 3.0.0

### ags_wave_find_near_timestamp ()

    GList *
    ags_wave_find_near_timestamp (GList *wave,
                                  guint line,
                                  AgsTimestamp *timestamp);

Retrieve appropriate wave for timestamp.

#### Parameters

wave | the GList containing AgsWave. | [element-type AgsAudio.Wave][transfer none]
line | the matching audio channel |
timestamp | the matching AgsTimestamp, or `NULL` to match any timestamp |

#### Returns

Next matching GList or `NULL` if not found.

[element-type AgsAudio.Wave][transfer none]

Since: 3.0.0

### ags_wave_sort_func ()

    gint
    ags_wave_sort_func (gconstpointer a,
                        gconstpointer b);

Compare `a` and `b` .

#### Parameters

a | the AgsWave |
b | another AgsWave |

#### Returns

0 if equal, -1 if smaller and 1 if bigger timestamp

Since: 3.0.0

### ags_wave_get_audio ()

    GObject *
    ags_wave_get_audio (AgsWave *wave);

Get audio.

#### Parameters

wave | the AgsWave |

#### Returns

the AgsAudio.

[transfer full]

Since: 3.1.0

### ags_wave_set_audio ()

    void
    ags_wave_set_audio (AgsWave *wave,
                        GObject *audio);

Set audio.

#### Parameters

wave | the AgsWave |
audio | the AgsAudio |

Since: 3.1.0

### ags_wave_get_line ()

    guint
    ags_wave_get_line (AgsWave *wave);

Gets line.

#### Parameters

wave | the AgsWave |

#### Returns

the line

Since: 3.1.0

### ags_wave_set_line ()

    void
    ags_wave_set_line (AgsWave *wave,
                       guint line);

Sets line.

#### Parameters

wave | the AgsWave |
line | the line |

Since: 3.1.0

### ags_wave_get_samplerate ()

    guint
    ags_wave_get_samplerate (AgsWave *wave);

Gets samplerate.

#### Parameters

wave | the AgsWave |

#### Returns

the samplerate

Since: 3.1.0

### ags_wave_set_samplerate ()

    void
    ags_wave_set_samplerate (AgsWave *wave,
                             guint samplerate);

Set samplerate.

#### Parameters

wave | the AgsWave |
samplerate | the samplerate |

Since: 3.0.0

### ags_wave_get_buffer_size ()

    guint
    ags_wave_get_buffer_size (AgsWave *wave);

Gets buffer size.

#### Parameters

wave | the AgsWave |

#### Returns

the buffer size

Since: 3.1.0

### ags_wave_set_buffer_size ()

    void
    ags_wave_set_buffer_size (AgsWave *wave,
                              guint buffer_size);

Set buffer size.

#### Parameters

wave | the AgsWave |
buffer_size | the buffer size |

Since: 3.0.0

### ags_wave_get_format ()

    AgsSoundcardFormat
    ags_wave_get_format (AgsWave *wave);

Gets format.

#### Parameters

wave | the AgsWave |

#### Returns

the format

Since: 3.1.0

### ags_wave_set_format ()

    void
    ags_wave_set_format (AgsWave *wave,
                         AgsSoundcardFormat format);

Set format.

#### Parameters

wave | the AgsWave |
format | the format |

Since: 3.0.0

### ags_wave_get_timestamp ()

    AgsTimestamp *
    ags_wave_get_timestamp (AgsWave *wave);

Get timestamp.

#### Parameters

wave | the AgsWave |

#### Returns

the AgsTimestamp.

[transfer full]

Since: 3.1.0

### ags_wave_set_timestamp ()

    void
    ags_wave_set_timestamp (AgsWave *wave,
                            AgsTimestamp *timestamp);

Set timestamp.

#### Parameters

wave | the AgsWave |
timestamp | the AgsTimestamp |

Since: 3.1.0

### ags_wave_get_buffer ()

    GList *
    ags_wave_get_buffer (AgsWave *wave);

Get buffer.

#### Parameters

wave | the AgsWave |

#### Returns

the GList containig AgsBuffer.

[element-type AgsAudio.Buffer][transfer full]

Since: 3.1.0

### ags_wave_set_buffer ()

    void
    ags_wave_set_buffer (AgsWave *wave,
                         GList *buffer);

Set buffer by replacing existing.

#### Parameters

wave | the AgsWave |
buffer | the GList containing AgsBuffer. | [element-type AgsAudio.Buffer][transfer full]

Since: 3.1.0

### ags_wave_add ()

    GList *
    ags_wave_add (GList *wave,
                  AgsWave *new_wave);

Add `new_wave` sorted to `wave`

#### Parameters

wave | the GList containing AgsWave. | [element-type AgsAudio.Wave][transfer none]
new_wave | the AgsWave to add |

#### Returns

the new beginning of `wave` .

[element-type AgsAudio.Wave][transfer none]

Since: 3.0.0

### ags_wave_add_buffer ()

    void
    ags_wave_add_buffer (AgsWave *wave,
                         AgsBuffer *buffer,
                         gboolean use_selection_list);

Add `buffer` to `wave` .

#### Parameters

wave | the AgsWave |
buffer | the AgsBuffer to add |
use_selection_list | if `TRUE` add to selection, else to default wave |

Since: 3.0.0

### ags_wave_remove_buffer ()

    void
    ags_wave_remove_buffer (AgsWave *wave,
                            AgsBuffer *buffer,
                            gboolean use_selection_list);

Removes `buffer` from `wave` .

#### Parameters

wave | the AgsWave |
buffer | the AgsBuffer to remove |
use_selection_list | if `TRUE` remove from selection, else from default wave |

Since: 3.0.0

### ags_wave_get_selection ()

    GList *
    ags_wave_get_selection (AgsWave *wave);

Retrieve selection.

#### Parameters

wave | the AgsWave |

#### Returns

the selection.

[element-type AgsAudio.Buffer][transfer none]

Since: 3.0.0

### ags_wave_is_buffer_selected ()

    gboolean
    ags_wave_is_buffer_selected (AgsWave *wave,
                                 AgsBuffer *buffer);

Check selection for buffer.

#### Parameters

wave | the AgsWave |
buffer | the AgsBuffer to check for |

#### Returns

`TRUE` if selected otherwise `FALSE`

Since: 3.0.0

### ags_wave_find_point ()

    AgsBuffer *
    ags_wave_find_point (AgsWave *wave,
                         guint64 x,
                         gboolean use_selection_list);

Find buffers by offset.

#### Parameters

wave | the AgsWave |
x | offset |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the matching buffer as AgsBuffer.

[transfer none]

Since: 3.0.0

### ags_wave_find_exact_point ()

    AgsBuffer *
    ags_wave_find_exact_point (AgsWave *wave,
                               guint64 x,
                               gboolean use_selection_list);

Find buffers by offset.

#### Parameters

wave | the AgsWave |
x | offset |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the matching buffer as AgsBuffer.

[transfer none]

Since: 3.14.6

### ags_wave_find_region ()

    GList *
    ags_wave_find_region (AgsWave *wave,
                          guint64 x0,
                          guint64 x1,
                          gboolean use_selection_list);

Find buffers by offset and region.

#### Parameters

wave | the AgsWave |
x0 | x start offset |
x1 | x end offset |
use_selection_list | if `TRUE` selection is searched |

#### Returns

the matching buffers as GList.

[element-type AgsAudio.Buffer][transfer container]

Since: 3.0.0

### ags_wave_free_selection ()

    void
    ags_wave_free_selection (AgsWave *wave);

Clear selection.

#### Parameters

wave | the AgsWave |

Since: 3.0.0

### ags_wave_free_all_selection ()

    void
    ags_wave_free_all_selection (GList *wave);

Clear all selection of `wave` .

#### Parameters

wave | the GList containing AgsWave |

Since: 3.14.10

### ags_wave_add_region_to_selection ()

    void
    ags_wave_add_region_to_selection (AgsWave *wave,
                                      guint64 x0,
                                      guint64 x1,
                                      gboolean replace_current_selection);

Add buffer within region to selection.

#### Parameters

wave | the AgsWave |
x0 | x start offset |
x1 | x end offset |
replace_current_selection | if `TRUE` selection is replaced |

Since: 3.0.0

### ags_wave_remove_region_from_selection ()

    void
    ags_wave_remove_region_from_selection (AgsWave *wave,
                                           guint64 x0,
                                           guint64 x1);

Remove buffers within region of selection.

#### Parameters

wave | the AgsWave |
x0 | x start offset |
x1 | x end offset |

Since: 3.0.0

### ags_wave_add_all_to_selection ()

    void
    ags_wave_add_all_to_selection (AgsWave *wave);

Select all buffer to selection.

#### Parameters

wave | the AgsWave |

Since: 3.0.0

### ags_wave_copy_selection ()

    xmlNode *
    ags_wave_copy_selection (AgsWave *wave);

Copy selection to clipboard.

#### Parameters

wave | the AgsWave |

#### Returns

the selection as XML.

[transfer none]

Since: 3.0.0

### ags_wave_cut_selection ()

    xmlNode *
    ags_wave_cut_selection (AgsWave *wave);

Cut selection to clipboard.

#### Parameters

wave | the AgsWave |

#### Returns

the selection as xmlNode.

[transfer none]

Since: 3.0.0

### ags_wave_copy_selection_as_base64 ()

    gchar *
    ags_wave_copy_selection_as_base64 (AgsWave *wave);

Copy selection to clipboard.

#### Parameters

wave | the AgsWave |

#### Returns

the selection as base64.

[transfer none]

Since: 6.16.0

### ags_wave_cut_selection_as_base64 ()

    gchar *
    ags_wave_cut_selection_as_base64 (AgsWave *wave);

Cut selection to clipboard.

#### Parameters

wave | the AgsWave |

#### Returns

the selection as base64.

[transfer none]

Since: 6.16.0

### ags_wave_insert_from_clipboard ()

    void
    ags_wave_insert_from_clipboard (AgsWave *wave,
                                    xmlNode *wave_node,
                                    gboolean reset_x_offset,
                                    guint64 x_offset,
                                    gdouble delay,
                                    guint attack);

Paste previously copied buffers.

#### Parameters

wave | the AgsWave |
wave_node | the clipboard XML data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
delay | the delay to be used |
attack | the attack to be used |

Since: 3.0.0

### ags_wave_insert_from_clipboard_extended ()

    void
    ags_wave_insert_from_clipboard_extended
                                   (AgsWave *wave,
                                    xmlNode *wave_node,
                                    gboolean reset_x_offset,
                                    guint64 x_offset,
                                    gdouble delay,
                                    guint attack,
                                    gboolean match_line,
                                    gboolean do_replace);

Paste previously copied buffers.

#### Parameters

wave | the AgsWave |
wave_node | the clipboard XML data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
delay | the delay to be used |
attack | the attack to be used |
match_line | only paste if channel matches |
do_replace | if `TRUE` current data is replaced, otherwise additive mixing is performed |

Since: 3.0.0

### ags_wave_insert_base64_from_clipboard ()

    void
    ags_wave_insert_base64_from_clipboard (AgsWave *wave,
                                           gchar *wave_base64,
                                           gboolean reset_x_offset,
                                           guint64 x_offset,
                                           gdouble delay,
                                           guint attack);

Paste previously copied buffers.

#### Parameters

wave | the AgsWave |
wave_base64 | the clipboard base64 data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
delay | the delay to be used |
attack | the attack to be used |

Since: 6.16.0

### ags_wave_insert_base64_from_clipboard_extended ()

    void
    ags_wave_insert_base64_from_clipboard_extended
                                   (AgsWave *wave,
                                    gchar *wave_base64,
                                    gboolean reset_x_offset,
                                    guint64 x_offset,
                                    gdouble delay,
                                    guint attack,
                                    gboolean match_line,
                                    gboolean do_replace);

Paste previously copied buffers.

#### Parameters

wave | the AgsWave |
wave_base64 | the clipboard base64 data |
reset_x_offset | if `TRUE` `x_offset` used as cursor |
x_offset | region start cursor offset |
delay | the delay to be used |
attack | the attack to be used |
match_line | only paste if channel matches |
do_replace | if `TRUE` current data is replaced, otherwise additive mixing is performed |

Since: 6.16.0

### ags_wave_new ()

    AgsWave *
    ags_wave_new (GObject *audio,
                  guint line);

Creates a new instance of AgsWave.

#### Parameters

audio | the assigned AgsAudio |
line | the line to be used |

#### Returns

a new AgsWave

Since: 3.0.0

## Types and Values

### AGS_WAVE_DEFAULT_BPM

    #define AGS_WAVE_DEFAULT_BPM (120.0)

### AGS_WAVE_TICS_PER_BEAT

    #define AGS_WAVE_TICS_PER_BEAT (1.0)

### AGS_WAVE_MINIMUM_BUFFER_LENGTH

    #define AGS_WAVE_MINIMUM_BUFFER_LENGTH (1.0 / 16.0)

### AGS_WAVE_DEFAULT_BUFFER_LENGTH

    #define AGS_WAVE_DEFAULT_BUFFER_LENGTH (64.0)

### AGS_WAVE_DEFAULT_LENGTH

    #define AGS_WAVE_DEFAULT_LENGTH ((60 * AGS_SOUNDCARD_DEFAULT_SAMPLERATE / AGS_WAVE_DEFAULT_BPM / 4) * 16 * 16 * 1200 / AGS_WAVE_TICS_PER_BEAT)

### AGS_WAVE_DEFAULT_JIFFIE

    #define AGS_WAVE_DEFAULT_JIFFIE (60.0 / AGS_WAVE_DEFAULT_BPM / AGS_WAVE_TICS_PER_BEAT)

### AGS_WAVE_DEFAULT_DURATION

    #define AGS_WAVE_DEFAULT_DURATION (AGS_WAVE_DEFAULT_LENGTH * AGS_WAVE_DEFAULT_JIFFIE * AGS_USEC_PER_SEC)

### AGS_WAVE_DEFAULT_OFFSET

    #define AGS_WAVE_DEFAULT_OFFSET (AGS_WAVE_DEFAULT_BUFFER_LENGTH * AGS_SOUNDCARD_DEFAULT_SAMPLERATE)

### AGS_WAVE_CLIPBOARD_VERSION

    #define AGS_WAVE_CLIPBOARD_VERSION "6.16.0"

### AGS_WAVE_CLIPBOARD_TYPE

    #define AGS_WAVE_CLIPBOARD_TYPE "AgsWaveClipboardXml"

### AGS_WAVE_CLIPBOARD_FORMAT

    #define AGS_WAVE_CLIPBOARD_FORMAT "AgsWaveNativeLevel"

### AGS_WAVE_CLIPBOARD_XML_TYPE

    #define AGS_WAVE_CLIPBOARD_XML_TYPE "AgsWaveClipboardXml"

### AGS_WAVE_CLIPBOARD_BASE64_TYPE

    #define AGS_WAVE_CLIPBOARD_BASE64_TYPE "AgsWaveClipboardBase64"

### AGS_WAVE_CLIPBOARD_MAX_SIZE

    #define AGS_WAVE_CLIPBOARD_MAX_SIZE (64 * 1024 * 1024)

### enum AgsWaveFlags

Enum values to control the behavior or indicate internal state of AgsWave by enable/disable as flags.

#### Members

AGS_WAVE_BYPASS | ignore any wave data |

## Property Details

### The `“audio”` property

      “audio”                    AgsAudio *

The assigned AgsAudio

Owner: AgsWave

Flags: Read / Write

Since: 3.0.0

### The `“buffer”` property

      “buffer”                   gpointer

The assigned AgsBuffer

[transfer full]

Owner: AgsWave

Flags: Read / Write

Since: 3.0.0

### The `“buffer-size”` property

      “buffer-size”              guint

The audio buffer's buffer size.

Owner: AgsWave

Flags: Read / Write

Default value: 2048

Since: 3.0.0

### The `“format”` property

      “format”                   guint

The audio buffer's format.

Owner: AgsWave

Flags: Read / Write

Default value: 16

Since: 3.0.0

### The `“line”` property

      “line”                     guint

The wave's line.

Owner: AgsWave

Flags: Read / Write

Default value: 0

Since: 3.0.0

### The `“samplerate”` property

      “samplerate”               guint

The audio buffer's samplerate.

Owner: AgsWave

Flags: Read / Write

Default value: 44100

Since: 3.0.0

### The `“timestamp”` property

      “timestamp”                AgsTimestamp *

The wave's timestamp.

Owner: AgsWave

Flags: Read / Write

Since: 3.0.0