.. _stdlib_audio_record:

====================================
Microphone capture and record-to-WAV
====================================

.. das:module:: audio_record

Module audio_record



++++++++++
Structures
++++++++++

.. _struct-audio_record-AudioDeviceInfo:

.. das:attribute:: AudioDeviceInfo

A capture (microphone) device, as returned by `sound_record_list_devices`.

:Fields: * **name** : string - < Human-readable device name.

         * **is_default** : bool - < True if this is the system default input device.

         * **index** : int - < Index to pass as `device_index` to `sound_record_start` / `record_to_wav`.




+++++++++
Recording
+++++++++

  *  :ref:`record_to_wav (fname: string; seconds: float; rate: int = 44100; channels: int = 1; device_index: int = -1) : bool <function-audio_record_record_to_wav_string_float_int_int_int>`
  *  :ref:`sound_record_list_devices () : array\<AudioDeviceInfo\> <function-audio_record_sound_record_list_devices>`

.. _function-audio_record_record_to_wav_string_float_int_int_int:

.. das:function:: record_to_wav(fname: string; seconds: float; rate: int = 44100; channels: int = 1; device_index: int = -1) : bool

Record `seconds` of audio from the microphone into a 16-bit PCM WAV file. Blocks until done.
Returns false (and writes nothing) on invalid arguments, if a recording is already active, if
the device fails to open, produces no audio, or stalls mid-capture, or if the WAV cannot be written.


:Arguments: * **fname** : string

            * **seconds** : float

            * **rate** : int

            * **channels** : int

            * **device_index** : int

.. _function-audio_record_sound_record_list_devices:

.. das:function:: sound_record_list_devices() : array<AudioDeviceInfo>

Enumerate available capture (microphone) devices. Pass an entry's `index` to
`sound_record_start` / `record_to_wav` as `device_index`, or -1 for the system default.