Defines functions for microphone creation, control, audio data fetching, and
destruction. The implementation must handle multiple calls to `SbMicrophoneOpen`
and `SbMicrophoneClose` on the same microphone. For example, calling
`SbMicrophoneOpen` twice without an intervening `SbMicrophoneClose` must be
handled gracefully.

This API is not thread-safe and must be called from a single thread.

API Usage:

1. Query available microphones by calling `SbMicrophoneGetAvailable`.

2. Create a supported microphone using `SbMicrophoneCreate`, specifying a
   supported sample rate and buffer size. Verify the sample rate with
   `SbMicrophoneIsSampleRateSupported`.

3. Open the microphone port and start recording using `SbMicrophoneOpen`.

4. Periodically read audio data using `SbMicrophoneRead`.

5. Close the port and stop recording using `SbMicrophoneClose`.

6. Destroy the microphone with `SbMicrophoneDestroy`.

## Macros

### kSbMicrophoneIdInvalid

Well-defined value for an invalid microphone ID handle.

### kSbMicrophoneInvalid

Well-defined value for an invalid microphone handle.

## Enums

### SbMicrophoneType

All possible microphone types.

#### Values

- `kSbMicrophoneCamera`

  Built-in camera microphone.
- `kSbMicrophoneUSBHeadset`

  USB headset microphone (wired or wireless).
- `kSbMicrophoneVRHeadset`

  VR headset microphone.
- `kSBMicrophoneAnalogHeadset`

  Analog headset microphone.
- `kSbMicrophoneUnknown`

  Unknown microphone type. Used if the microphone does not map to other enum
  values.

## Typedefs

### SbMicrophone

An opaque handle to an implementation-private structure that represents a
microphone.

#### Definition

    typedef struct SbMicrophonePrivate* SbMicrophone

### SbMicrophoneId

An opaque handle to an implementation-private structure that represents a
microphone ID.

#### Definition

    typedef struct SbMicrophoneIdPrivate* SbMicrophoneId

## Structs

### SbMicrophoneInfo

Microphone information.

#### Members

- `SbMicrophoneId id`

  Microphone ID.
- `SbMicrophoneType type`

  Microphone type.
- `int max_sample_rate_hz`

  The microphone's maximum supported sampling rate.
- `int min_read_size`

  The minimum read size (in bytes) required for each read.
- `char label`

  A user-friendly name for the microphone (for example, "Headset Microphone").
  Can be empty. The string must be null-terminated.

## Functions

### SbMicrophoneClose

Closes the microphone port, stops recording on `microphone`, and clears any
unread data from the buffer. If the microphone is already stopped, this call is
ignored. Returns `true` if the microphone is successfully closed.

- `microphone`: The microphone to close.

#### Declaration

    bool SbMicrophoneClose(SbMicrophone microphone)

### SbMicrophoneCreate

Creates a microphone with the specified ID, sample rate, and buffer size.
Starboard only requires support for one active microphone at a time; creating a
second microphone before destroying the first may fail.

Returns the newly created `SbMicrophone` object. Returns `kSbMicrophoneInvalid`
if the microphone is already initialized, the sample rate is unsupported, or the
buffer size is invalid.

- `id`: The ID that will be assigned to the newly created SbMicrophone.

- `sample_rate_in_hz`: The new microphone's audio sample rate in Hz.

- `buffer_size_bytes`: The size of the buffer where signed 16-bit integer
  audio data is temporarily cached during capture. Audio data is removed from
  the buffer after it is read. New data can be read from this buffer in chunks
  smaller than the buffer size. This parameter must be greater than zero, and
  ideally a power of two (`2^n`).

#### Declaration

    SbMicrophone SbMicrophoneCreate(SbMicrophoneId id, int sample_rate_in_hz, int buffer_size_bytes)

### SbMicrophoneDestroy

Destroys a microphone. If the microphone is recording, it is stopped before
being destroyed. Any unread recorded data is discarded.

#### Declaration

    void SbMicrophoneDestroy(SbMicrophone microphone)

### SbMicrophoneGetAvailable

Retrieves information for all available microphones and stores it in
`out_info_array`. Returns the number of available microphones. If this count
exceeds `info_array_size`, the array is filled to capacity with available
microphone info, and the total count of available microphones is returned. A
negative return value indicates an error.

- `out_info_array`: The destination buffer for available microphone info.

- `info_array_size`: The capacity of `out_info_array`.

#### Declaration

    int SbMicrophoneGetAvailable(SbMicrophoneInfo *out_info_array, int info_array_size)

### SbMicrophoneIdIsValid

Indicates whether the given microphone ID is valid.

#### Declaration

    static bool SbMicrophoneIdIsValid(SbMicrophoneId id)

### SbMicrophoneIsSampleRateSupported

Returns whether the microphone supports the specified sample rate.

#### Declaration

    bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id, int sample_rate_in_hz)

### SbMicrophoneIsValid

Indicates whether the given microphone is valid.

#### Declaration

    static bool SbMicrophoneIsValid(SbMicrophone microphone)

### SbMicrophoneOpen

Opens the microphone port and starts recording on `microphone`. Once started,
call `SbMicrophoneRead` periodically to retrieve audio data. If the microphone
is already open, this call clears the unread buffer. Returns `true` if the
microphone is successfully opened.

- `microphone`: The microphone to open.

#### Declaration

    bool SbMicrophoneOpen(SbMicrophone microphone)

### SbMicrophoneRead

Retrieves the recorded audio data from the microphone and writes that data to
`out_audio_data`.

Returns the number of bytes read (greater than or equal to zero). The returned
size does not exceed `audio_data_size` or the internal buffer size. Returns a
negative value on error.

Call this function frequently. If the internal buffer (configured in
`SbMicrophoneCreate`) fills up, new audio data is discarded. You cannot read
data from a stopped microphone.

- `microphone`: The microphone to read from.

- `out_audio_data`: The destination buffer for the read data.

- `audio_data_size`: The number of bytes to read. If `audio_data_size` is less
  than `min_read_size` (from `SbMicrophoneInfo`), any additional audio data
  read from the device is discarded.

#### Declaration

    int SbMicrophoneRead(SbMicrophone microphone, void *out_audio_data, int audio_data_size)