## AgsSoundcard

AgsSoundcard — unique access to soundcards

## Stability Level

Stable, unless otherwise indicated

## Functions

void | ags_soundcard_set_device ()
gchar * | ags_soundcard_get_device ()
void | ags_soundcard_set_presets ()
void | ags_soundcard_get_presets ()
void | ags_soundcard_list_cards ()
void | ags_soundcard_pcm_info ()
AgsSoundcardCapability | ags_soundcard_get_capability ()
gboolean | ags_soundcard_is_available ()
gboolean | ags_soundcard_is_starting ()
gboolean | ags_soundcard_is_playing ()
gboolean | ags_soundcard_is_recording ()
gchar * | ags_soundcard_get_uptime ()
void | ags_soundcard_play_init ()
void | ags_soundcard_play ()
void | ags_soundcard_record_init ()
void | ags_soundcard_record ()
void | ags_soundcard_stop ()
void | ags_soundcard_tic ()
void | ags_soundcard_offset_changed ()
void * | ags_soundcard_get_buffer ()
void * | ags_soundcard_get_next_buffer ()
void * | ags_soundcard_get_prev_buffer ()
void | ags_soundcard_lock_buffer ()
void | ags_soundcard_unlock_buffer ()
void | ags_soundcard_set_bpm ()
gdouble | ags_soundcard_get_bpm ()
guint | ags_soundcard_get_sub_block_count ()
gboolean | ags_soundcard_trylock_sub_block ()
void | ags_soundcard_unlock_sub_block ()

## Signals

void | offset-changed | Run Last
void | stop | Run Last
void | tic | Run Last

## Types and Values

#define | AGS_SOUNDCARD_DEFAULT_DSP_CHANNELS
#define | AGS_SOUNDCARD_MIN_DSP_CHANNELS
#define | AGS_SOUNDCARD_MAX_DSP_CHANNELS
#define | AGS_SOUNDCARD_DEFAULT_PCM_CHANNELS
#define | AGS_SOUNDCARD_MIN_PCM_CHANNELS
#define | AGS_SOUNDCARD_MAX_PCM_CHANNELS
#define | AGS_SOUNDCARD_DEFAULT_SAMPLERATE
#define | AGS_SOUNDCARD_MIN_SAMPLERATE
#define | AGS_SOUNDCARD_MAX_SAMPLERATE
#define | AGS_SOUNDCARD_DEFAULT_FORMAT
#define | AGS_SOUNDCARD_DEFAULT_BUFFER_SIZE
#define | AGS_SOUNDCARD_MIN_BUFFER_SIZE
#define | AGS_SOUNDCARD_MAX_BUFFER_SIZE
#define | AGS_SOUNDCARD_DEFAULT_USE_CACHE
#define | AGS_SOUNDCARD_DEFAULT_CACHE_BUFFER_SIZE
#define | AGS_SOUNDCARD_DEFAULT_BPM
#define | AGS_SOUNDCARD_DEFAULT_DELAY_FACTOR
#define | AGS_SOUNDCARD_DEFAULT_JIFFIE
#define | AGS_SOUNDCARD_DEFAULT_TACT
#define | AGS_SOUNDCARD_DEFAULT_TACT_JIFFIE
#define | AGS_SOUNDCARD_DEFAULT_TACTRATE
#define | AGS_SOUNDCARD_DEFAULT_SCALE
#define | AGS_SOUNDCARD_DEFAULT_DELAY
#define | AGS_SOUNDCARD_DEFAULT_PERIOD
#define | AGS_SOUNDCARD_DEFAULT_LOOP_LEFT
#define | AGS_SOUNDCARD_DEFAULT_LOOP_RIGHT
#define | AGS_SOUNDCARD_DEFAULT_OVERCLOCK
#define | AGS_SOUNDCARD_DEFAULT_SUB_BLOCK_COUNT
enum | AgsSoundcardFormat
enum | AgsSoundcardCapability

## Object Hierarchy

        GEnum
        ╰── AgsSoundcardFormat
        GFlags
        ╰── AgsSoundcardCapability
        GInterface
        ╰── AgsSoundcard

## Includes

    #include <ags/object/ags_soundcard.h>

## Description

The AgsSoundcard interface gives you a unique access to audio devices.

## Functions

### ags_soundcard_set_device ()

    void
    ags_soundcard_set_device (AgsSoundcard *soundcard,
                              gchar *card_id);

Set device.

#### Parameters

soundcard | the AgsSoundcard |
card_id | the device to set |

Since: 3.0.0

### ags_soundcard_get_device ()

    gchar *
    ags_soundcard_get_device (AgsSoundcard *soundcard);

Get device.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

the device's identifier

Since: 3.0.0

### ags_soundcard_set_presets ()

    void
    ags_soundcard_set_presets (AgsSoundcard *soundcard,
                               guint channels,
                               guint rate,
                               guint buffer_size,
                               AgsSoundcardFormat format);

Set presets.

#### Parameters

soundcard | the AgsSoundcard |
channels | the audio channels |
rate | the samplerate |
buffer_size | the buffer size |
format | the format |

Since: 3.0.0

### ags_soundcard_get_presets ()

    void
    ags_soundcard_get_presets (AgsSoundcard *soundcard,
                               guint *channels,
                               guint *rate,
                               guint *buffer_size,
                               AgsSoundcardFormat *format);

Get presets.

#### Parameters

soundcard | the AgsSoundcard |
channels | the audio channels. | [out]
rate | the samplerate. | [out]
buffer_size | the buffer size. | [out]
format | the format. | [out]

Since: 3.0.0

### ags_soundcard_list_cards ()

    void
    ags_soundcard_list_cards (AgsSoundcard *soundcard,
                              GList **card_id,
                              GList **card_name);

Retrieve `card_id` and `card_name` as a list of strings.

#### Parameters

soundcard | the AgsSoundcard |
card_id | a list containing card ids. | [element-type utf8][out callee-allocates][array zero-terminated=1][transfer full]
card_name | a list containing card names. | [element-type utf8][out callee-allocates][array zero-terminated=1][transfer full]

Since: 3.0.0

### ags_soundcard_pcm_info ()

    void
    ags_soundcard_pcm_info (AgsSoundcard *soundcard,
                            gchar *card_id,
                            guint *channels_min,
                            guint *channels_max,
                            guint *rate_min,
                            guint *rate_max,
                            guint *buffer_size_min,
                            guint *buffer_size_max,
                            GError **error);

Retrieve detailed information of `card_id` soundcard.

#### Parameters

soundcard | the AgsSoundcard |
card_id | the selected soundcard by its string identifier |
channels_min | min channels supported. | [out]
channels_max | max channels supported. | [out]
rate_min | min samplerate supported. | [out]
rate_max | max samplerate supported. | [out]
buffer_size_min | min buffer size supported by soundcard. | [out]
buffer_size_max | max buffer size supported by soundcard. | [out]
error | an error that may occure |

Since: 3.0.0

### ags_soundcard_get_capability ()

    AgsSoundcardCapability
    ags_soundcard_get_capability (AgsSoundcard *soundcard);

Retrieve AgsSoundcardCapability information.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

the capablities flags

Since: 3.0.0

### ags_soundcard_is_available ()

    gboolean
    ags_soundcard_is_available (AgsSoundcard *soundcard);

Get available.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

`TRUE` if available, else `FALSE`

Since: 3.0.0

### ags_soundcard_is_starting ()

    gboolean
    ags_soundcard_is_starting (AgsSoundcard *soundcard);

Get starting.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

`TRUE` if starting, else `FALSE`

Since: 3.0.0

### ags_soundcard_is_playing ()

    gboolean
    ags_soundcard_is_playing (AgsSoundcard *soundcard);

Get playing.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

`TRUE` if playing, else `FALSE`

Since: 3.0.0

### ags_soundcard_is_recording ()

    gboolean
    ags_soundcard_is_recording (AgsSoundcard *soundcard);

Get recording.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

`TRUE` if recording, else `FALSE`

Since: 3.0.0

### ags_soundcard_get_uptime ()

    gchar *
    ags_soundcard_get_uptime (AgsSoundcard *soundcard);

Get playback time as string.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

playback time as string

Since: 3.0.0

### ags_soundcard_play_init ()

    void
    ags_soundcard_play_init (AgsSoundcard *soundcard,
                             GError **error);

Initializes the soundcard for playback.

#### Parameters

soundcard | the AgsSoundcard |
error | an error that may occure |

Since: 3.0.0

### ags_soundcard_play ()

    void
    ags_soundcard_play (AgsSoundcard *soundcard,
                        GError **error);

Plays the current buffer of soundcard.

#### Parameters

soundcard | the AgsSoundcard |
error | an error that may occure |

Since: 3.0.0

### ags_soundcard_record_init ()

    void
    ags_soundcard_record_init (AgsSoundcard *soundcard,
                               GError **error);

Initializes the soundcard for recordback.

#### Parameters

soundcard | the AgsSoundcard |
error | an error that may occure |

Since: 3.0.0

### ags_soundcard_record ()

    void
    ags_soundcard_record (AgsSoundcard *soundcard,
                          GError **error);

Records the current buffer of soundcard.

#### Parameters

soundcard | the AgsSoundcard |
error | an error that may occure |

Since: 3.0.0

### ags_soundcard_stop ()

    void
    ags_soundcard_stop (AgsSoundcard *soundcard);

Stops the soundcard from playing to it.

#### Parameters

soundcard | the AgsSoundcard |

Since: 3.0.0

### ags_soundcard_tic ()

    void
    ags_soundcard_tic (AgsSoundcard *soundcard);

Every call to play may generate a tic.

#### Parameters

soundcard | the AgsSoundcard |

Since: 3.0.0

### ags_soundcard_offset_changed ()

    void
    ags_soundcard_offset_changed (AgsSoundcard *soundcard,
                                  guint note_offset);

Callback when counter expires minor note offset.

#### Parameters

soundcard | the AgsSoundcard |
note_offset | the current note offset |

Since: 3.0.0

### ags_soundcard_get_buffer ()

    void *
    ags_soundcard_get_buffer (AgsSoundcard *soundcard);

Get current playback buffer.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

current playback buffer

Since: 3.0.0

### ags_soundcard_get_next_buffer ()

    void *
    ags_soundcard_get_next_buffer (AgsSoundcard *soundcard);

Get future playback buffer.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

next playback buffer

Since: 3.0.0

### ags_soundcard_get_prev_buffer ()

    void *
    ags_soundcard_get_prev_buffer (AgsSoundcard *soundcard);

Get future playback buffer.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

prev playback buffer

Since: 3.0.0

### ags_soundcard_lock_buffer ()

    void
    ags_soundcard_lock_buffer (AgsSoundcard *soundcard,
                               void *buffer);

Lock `buffer` .

#### Parameters

soundcard | the AgsSoundcard |
buffer | the buffer to lock |

Since: 3.0.0

### ags_soundcard_unlock_buffer ()

    void
    ags_soundcard_unlock_buffer (AgsSoundcard *soundcard,
                                 void *buffer);

Unlock `buffer` .

#### Parameters

soundcard | the AgsSoundcard |
buffer | the buffer to unlock |

Since: 3.0.0

### ags_soundcard_set_bpm ()

    void
    ags_soundcard_set_bpm (AgsSoundcard *soundcard,
                           gdouble bpm);

Set current playback bpm.

#### Parameters

soundcard | the AgsSoundcard |
bpm | the bpm to set |

Since: 3.0.0

### ags_soundcard_get_bpm ()

    gdouble
    ags_soundcard_get_bpm (AgsSoundcard *soundcard);

Get current playback bpm.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

bpm

Since: 3.0.0

### ags_soundcard_get_sub_block_count ()

    guint
    ags_soundcard_get_sub_block_count (AgsSoundcard *soundcard);

`ags_soundcard_get_sub_block_count` is deprecated and should not be used in newly-written code.

Get sub block count.

#### Parameters

soundcard | the AgsSoundcard |

#### Returns

the sub block count

Since: 3.0.0

### ags_soundcard_trylock_sub_block ()

    gboolean
    ags_soundcard_trylock_sub_block (AgsSoundcard *soundcard,
                                     void *buffer,
                                     guint sub_block);

Trylock sub block.

#### Parameters

soundcard | the AgsSoundcard |
buffer | the buffer to lock |
sub_block | and its sub block |

#### Returns

`TRUE` on success, otherwise `FALSE`

Since: 3.0.0

### ags_soundcard_unlock_sub_block ()

    void
    ags_soundcard_unlock_sub_block (AgsSoundcard *soundcard,
                                    void *buffer,
                                    guint sub_block);

Unlock sub block.

#### Parameters

soundcard | the AgsSoundcard |
buffer | the buffer to lock |
sub_block | and its sub block |

Since: 3.0.0

## Types and Values

### AGS_SOUNDCARD_DEFAULT_DSP_CHANNELS

    #define AGS_SOUNDCARD_DEFAULT_DSP_CHANNELS (2)

### AGS_SOUNDCARD_MIN_DSP_CHANNELS

    #define AGS_SOUNDCARD_MIN_DSP_CHANNELS (1)

### AGS_SOUNDCARD_MAX_DSP_CHANNELS

    #define AGS_SOUNDCARD_MAX_DSP_CHANNELS (64)

### AGS_SOUNDCARD_DEFAULT_PCM_CHANNELS

    #define AGS_SOUNDCARD_DEFAULT_PCM_CHANNELS (2)

### AGS_SOUNDCARD_MIN_PCM_CHANNELS

    #define AGS_SOUNDCARD_MIN_PCM_CHANNELS (1)

### AGS_SOUNDCARD_MAX_PCM_CHANNELS

    #define AGS_SOUNDCARD_MAX_PCM_CHANNELS (64)

### AGS_SOUNDCARD_DEFAULT_SAMPLERATE

    #define AGS_SOUNDCARD_DEFAULT_SAMPLERATE (44100.0)

### AGS_SOUNDCARD_MIN_SAMPLERATE

    #define AGS_SOUNDCARD_MIN_SAMPLERATE (8000.0)

### AGS_SOUNDCARD_MAX_SAMPLERATE

    #define AGS_SOUNDCARD_MAX_SAMPLERATE (5644800.0)

### AGS_SOUNDCARD_DEFAULT_FORMAT

    #define AGS_SOUNDCARD_DEFAULT_FORMAT (AGS_SOUNDCARD_SIGNED_16_BIT)

### AGS_SOUNDCARD_DEFAULT_BUFFER_SIZE

    #define AGS_SOUNDCARD_DEFAULT_BUFFER_SIZE (2048)

### AGS_SOUNDCARD_MIN_BUFFER_SIZE

    #define AGS_SOUNDCARD_MIN_BUFFER_SIZE (16)

### AGS_SOUNDCARD_MAX_BUFFER_SIZE

    #define AGS_SOUNDCARD_MAX_BUFFER_SIZE (16384)

### AGS_SOUNDCARD_DEFAULT_USE_CACHE

    #define AGS_SOUNDCARD_DEFAULT_USE_CACHE (FALSE)

### AGS_SOUNDCARD_DEFAULT_CACHE_BUFFER_SIZE

    #define AGS_SOUNDCARD_DEFAULT_CACHE_BUFFER_SIZE (4096)

### AGS_SOUNDCARD_DEFAULT_BPM

    #define AGS_SOUNDCARD_DEFAULT_BPM (120.0)

### AGS_SOUNDCARD_DEFAULT_DELAY_FACTOR

    #define AGS_SOUNDCARD_DEFAULT_DELAY_FACTOR (1.0 / 4.0)

### AGS_SOUNDCARD_DEFAULT_JIFFIE

    #define AGS_SOUNDCARD_DEFAULT_JIFFIE ((double) AGS_SOUNDCARD_DEFAULT_SAMPLERATE / (double) AGS_SOUNDCARD_DEFAULT_BUFFER_SIZE)

### AGS_SOUNDCARD_DEFAULT_TACT

    #define AGS_SOUNDCARD_DEFAULT_TACT (1.0 / 1.0)

### AGS_SOUNDCARD_DEFAULT_TACT_JIFFIE

    #define AGS_SOUNDCARD_DEFAULT_TACT_JIFFIE (60.0 / AGS_SOUNDCARD_DEFAULT_BPM * AGS_SOUNDCARD_DEFAULT_TACT)

### AGS_SOUNDCARD_DEFAULT_TACTRATE

    #define AGS_SOUNDCARD_DEFAULT_TACTRATE (1.0 / AGS_SOUNDCARD_DEFAULT_TACT_JIFFIE)

### AGS_SOUNDCARD_DEFAULT_SCALE

    #define AGS_SOUNDCARD_DEFAULT_SCALE (1.0)

### AGS_SOUNDCARD_DEFAULT_DELAY

    #define AGS_SOUNDCARD_DEFAULT_DELAY ((60.0 * ((AGS_SOUNDCARD_DEFAULT_SAMPLERATE / AGS_SOUNDCARD_DEFAULT_BUFFER_SIZE) / AGS_SOUNDCARD_DEFAULT_BPM)) * ((1.0 / 16.0) * (1.0 / AGS_SOUNDCARD_DEFAULT_DELAY_FACTOR)))

### AGS_SOUNDCARD_DEFAULT_PERIOD

    #define AGS_SOUNDCARD_DEFAULT_PERIOD (2048.0)

### AGS_SOUNDCARD_DEFAULT_LOOP_LEFT

    #define AGS_SOUNDCARD_DEFAULT_LOOP_LEFT (0)

### AGS_SOUNDCARD_DEFAULT_LOOP_RIGHT

    #define AGS_SOUNDCARD_DEFAULT_LOOP_RIGHT (64)

### AGS_SOUNDCARD_DEFAULT_OVERCLOCK

    #define AGS_SOUNDCARD_DEFAULT_OVERCLOCK (2.0)

### AGS_SOUNDCARD_DEFAULT_SUB_BLOCK_COUNT

    #define AGS_SOUNDCARD_DEFAULT_SUB_BLOCK_COUNT (8)

### enum AgsSoundcardFormat

AgsSoundcardFormat specifies the audio data representation to be used.

#### Members

AGS_SOUNDCARD_SIGNED_8_BIT | signed 8 bit raw pcm data |
AGS_SOUNDCARD_SIGNED_16_BIT | signed 16 bit raw pcm data |
AGS_SOUNDCARD_SIGNED_24_BIT | signed 24 bit raw pcm data |
AGS_SOUNDCARD_SIGNED_32_BIT | signed 32 bit raw pcm data |
AGS_SOUNDCARD_SIGNED_64_BIT | signed 64 bit raw pcm data |
AGS_SOUNDCARD_FLOAT | float raw pcm data |
AGS_SOUNDCARD_DOUBLE | double raw pcm data |
AGS_SOUNDCARD_COMPLEX | complex audio data |

### enum AgsSoundcardCapability

Enum values to tell about capability.

#### Members

AGS_SOUNDCARD_CAPABILITY_PLAYBACK | capability playback |
AGS_SOUNDCARD_CAPABILITY_CAPTURE | capability capture |
AGS_SOUNDCARD_CAPABILITY_DUPLEX | capability duplex |

## Signal Details

### The `“offset-changed”` signal

    void
    user_function (AgsSoundcard *soundcard,
                   guint         note_offset,
                   gpointer      user_data)

The ::offset-changed signal notifies about changed position within notation.

#### Parameters

soundcard | the AgsSoundcard object |
note_offset | new notation offset |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“stop”` signal

    void
    user_function (AgsSoundcard *soundcard,
                   gpointer      user_data)

The ::stop signal is emitted every stop of the soundcard. This notifies about a newly played buffer.

#### Parameters

soundcard | the AgsSoundcard object |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0

### The `“tic”` signal

    void
    user_function (AgsSoundcard *soundcard,
                   gpointer      user_data)

The ::tic signal is emitted every tic of the soundcard. This notifies about a newly played buffer.

#### Parameters

soundcard | the AgsSoundcard object |
user_data | user data set when the signal handler was connected. |

Flags: Run Last

Since: 3.0.0