src/cobalt/site/docs/reference/starboard/modules/microphone.md

---
layout: doc
title: "Starboard Module Reference: microphone.h"
---

Defines functions for microphone creation, control, audio data fetching, and
destruction. This module supports multiple calls to `SbMicrophoneOpen` and
`SbMicrophoneClose`, and the implementation should handle multiple calls to one
of those functions on the same microphone. For example, your implementation
should handle cases where `SbMicrophoneOpen` is called twice on the same
microphone without a call to `SbMicrophoneClose` in between.

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

How to use this API:

1.  Call `SbMicrophoneGetAvailableInfos` to get a list of available microphone
    information.

1.  Create a supported microphone, using `SbMicrophoneCreate`, with enough
    buffer size and sample rate. Use `SbMicrophoneIsSampleRateSupported` to
    verify the sample rate.

1.  Use `SbMicrophoneOpen` to open the microphone port and start recording audio
    data.

1.  Periodically read out the data from microphone with `SbMicrophoneRead`.

1.  Call `SbMicrophoneClose` to close the microphone port and stop recording
    audio data.

1.  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 microphone in camera.
*   `kSbMicrophoneUSBHeadset`

    Microphone in the headset that can be a wired or wireless USB headset.
*   `kSbMicrophoneVRHeadset`

    Microphone in the VR headset.
*   `kSBMicrophoneAnalogHeadset`

    Microphone in the analog headset.
*   `kSbMicrophoneUnknown`

    Unknown microphone type. The microphone could be different than the other
    enum descriptions or could fall under one of those descriptions.

## 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 required for each read from microphone.
*   `char label`

    Name of the microphone. Can be empty. This should indicate the friendly name
    of the microphone type. For example, "Headset Microphone". The string must
    be null terminated.

## Functions ##

### SbMicrophoneClose ###

Closes the microphone port, stops recording audio on `microphone`, and clears
the unread buffer if it is not empty. If the microphone has already been
stopped, this call is ignored. The return value indicates whether the microphone
is closed.

`microphone`: The microphone to close.

#### Declaration ####

```
bool SbMicrophoneClose(SbMicrophone microphone)
```

### SbMicrophoneCreate ###

Creates a microphone with the specified ID, audio sample rate, and cached audio
buffer size. Starboard only requires support for creating one microphone at a
time, and implementations may return an error if a second microphone is created
before the first is destroyed.

The function returns the newly created SbMicrophone object. However, if you try
to create a microphone that has already been initialized, if the sample rate is
unavailable, or if the buffer size is invalid, the function should return
`kSbMicrophoneInvalid`.

`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 to during the capturing. The audio data is removed
from the audio buffer if it has been read, and new audio data can be read from
this buffer in smaller chunks than this size. This parameter must be set to a
value greater than zero and the ideal size is `2^n`.

#### Declaration ####

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

### SbMicrophoneDestroy ###

Destroys a microphone. If the microphone is in started state, it is first
stopped and then destroyed. Any data that has been recorded and not read is
thrown away.

#### Declaration ####

```
void SbMicrophoneDestroy(SbMicrophone microphone)
```

### SbMicrophoneGetAvailable ###

Retrieves all currently available microphone information and stores it in
`out_info_array`. The return value is the number of the available microphones.
If the number of available microphones is larger than `info_array_size`, then
`out_info_array` is filled up with as many available microphones as possible and
the actual number of available microphones is returned. A negative return value
indicates that an internal error occurred.

`out_info_array`: All currently available information about the microphone is
placed into this output parameter. `info_array_size`: The size 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 ###

Indicates whether the microphone supports the 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 audio on `microphone`.

Once started, the client needs to periodically call `SbMicrophoneRead` to
receive the audio data. If the microphone has already been started, this call
clears the unread buffer. The return value indicates whether the microphone is
open. `microphone`: The microphone that will be opened and will start recording
audio.

#### Declaration ####

```
bool SbMicrophoneOpen(SbMicrophone microphone)
```

### SbMicrophoneRead ###

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

The return value is zero or the positive number of bytes that were read. Neither
the return value nor `audio_data_size` exceeds the buffer size. A negative
return value indicates that an error occurred.

This function should be called frequently. Otherwise, the microphone only
buffers `buffer_size` bytes as configured in `SbMicrophoneCreate` and the new
audio data is thrown out. No audio data is read from a stopped microphone.

`microphone`: The microphone from which to retrieve recorded audio data.
`out_audio_data`: The buffer to which the retrieved data will be written.
`audio_data_size`: The number of requested bytes. If `audio_data_size` is
smaller than `min_read_size` of `SbMicrophoneInfo`, the extra audio data that
has already been read from the device is discarded.

#### Declaration ####

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