src/starboard/microphone.h

// Copyright 2016 Google Inc. All Rights Reserved.
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
// You may obtain a copy of the License at
//
//     http://www.apache.org/licenses/LICENSE-2.0
//
// Unless required by applicable law or agreed to in writing, software
// distributed under the License is distributed on an "AS IS" BASIS,
// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
// See the License for the specific language governing permissions and
// limitations under the License.

// Microphone creation, control, audio data fetching and destruction.
// Multiple calls to |SbMicrophoneOpen| and |SbMicrophoneClose| are allowed, and
// the implementation also should take care of same calls of open and close in a
// row on a microphone.
// This API is not threadsafe and must be called from a single thread.
//
// How to use this API:
// 1) |SbMicrophoneGetAvailableInfos| to get a list of available microphone
//    information.
// 2) Choose one to create microphone |SbMicrophoneCreate| with enough buffer
//    size and sample rate. The sample rate can be verified by
//    |SbMicrophoneIsSampleRateSupported|.
// 3) Open the microphone port and start recording audio data by
//    |SbMicrophoneOpen|.
// 4) Periodically read out the data from microphone by |SbMicrophoneRead|.
// 5) Close the microphone port and stop recording audio data by
//    |SbMicrophoneClose|.
// 6) Destroy the microphone |SbMicrophoneDestroy|.

#ifndef STARBOARD_MICROPHONE_H_
#define STARBOARD_MICROPHONE_H_

#include "starboard/configuration.h"
#include "starboard/export.h"
#include "starboard/types.h"

#if SB_HAS(MICROPHONE) && SB_VERSION(2)

#ifdef __cplusplus
extern "C" {
#endif

// All possible microphone types.
typedef enum SbMicrophoneType {
  // Build-in microphone in camera.
  kSbMicrophoneCamera,

  // Microphone in the headset which can be wire or wireless USB headset.
  kSbMicrophoneUSBHeadset,

  // Microphone in the VR headset.
  kSbMicrophoneVRHeadset,

  // Microphone in the analog headset.
  kSBMicrophoneAnalogHeadset,

  // Unknown microphone type. Microphone other than those listed or could be
  // either of those listed.
  kSbMicrophoneUnknown,
} SbMicrophoneType;

// An opaque handle to an implementation-private structure representing a
// microphone id.
typedef struct SbMicrophoneIdPrivate* SbMicrophoneId;

// Well-defined value for an invalid microphone id handle.
#define kSbMicrophoneIdInvalid ((SbMicrophoneId)NULL)

// Returns whether the given microphone id is valid.
static SB_C_INLINE bool SbMicrophoneIdIsValid(SbMicrophoneId id) {
  return id != kSbMicrophoneIdInvalid;
}

// Microphone information.
typedef struct SbMicrophoneInfo {
  // Microphone id.
  SbMicrophoneId id;

  // Microphone type.
  SbMicrophoneType type;

  // Microphone max supported sampling rate.
  int max_sample_rate_hz;

  // The minimum read size required for each read from microphone.
  int min_read_size;
} SbMicrophoneInfo;

// An opaque handle to an implementation-private structure representing a
// microphone.
typedef struct SbMicrophonePrivate* SbMicrophone;

// Well-defined value for an invalid microphone handle.
#define kSbMicrophoneInvalid ((SbMicrophone)NULL)

// Returns whether the given microphone is valid.
static SB_C_INLINE bool SbMicrophoneIsValid(SbMicrophone microphone) {
  return microphone != kSbMicrophoneInvalid;
}

// Gets all currently-available microphone information and the results are
// stored in |out_info_array|. |info_array_size| is the size of
// |out_info_array|.
// Returns the number of the available microphones. A negative return
// value indicates that an internal error has occurred. If the number of
// available microphones is larger than |info_array_size|, |out_info_array| will
// be filled up with as many available microphones as possible and the actual
// number of available microphones will be returned.
SB_EXPORT int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array,
                                       int info_array_size);

// Returns true if the sample rate is supported by the microphone.
SB_EXPORT bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id,
                                                 int sample_rate_in_hz);

// Creates a microphone with |id|, audio sample rate in HZ, and the size of
// the cached audio buffer.
//
// If you try to create a microphone that has already been initialized or
// the sample rate is unavailable or the buffer size is invalid, it should
// return |kSbMicrophoneInvalid|. |buffer_size_bytes| is the size of the buffer
// where signed 16-bit integer audio data is temporarily cached to during the
// capturing. The audio data will be removed from the audio buffer if it has
// been read. New audio data can be read from this buffer in smaller chunks than
// this size. |buffer_size_bytes| must be set to a value greater than zero and
// the ideal size is 2^n. We only require support for creating one microphone at
// a time, and that implementations may return an error if a second microphone
// is created before destroying the first.
SB_EXPORT SbMicrophone SbMicrophoneCreate(SbMicrophoneId id,
                                          int sample_rate_in_hz,
                                          int buffer_size_bytes);

// Opens the microphone port and starts recording audio on |microphone|.
//
// Once started, the client will have to periodically call |SbMicrophoneRead| to
// receive the audio data. If the microphone has already been started, this call
// will clear the unread buffer. The return value indicates if the microphone is
// open.
SB_EXPORT bool SbMicrophoneOpen(SbMicrophone microphone);

// Closes the microphone port and stops recording audio on |microphone|.
//
// Clear the unread buffer if it is not empty. If the microphone has already
// been stopped, this call would be ignored. The return value indicates if the
// microphone is closed.
SB_EXPORT bool SbMicrophoneClose(SbMicrophone microphone);

// Gets the recorded audio data from the microphone.
//
// |out_audio_data| is where the recorded audio data is written to.
// |audio_data_size| is the number of requested bytes. 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. Negative return value indicates
// an error. This function should be called frequently, otherwise microphone
// only buffers |buffer_size| bytes which is configured in |SbMicrophoneCreate|
// and the new audio data will be thrown out. No audio data will be read from a
// stopped microphone. If |audio_data_size| is smaller than |min_read_size| of
// |SbMicrophoneInfo|, the extra audio data which is already read from device
// will be discarded.
SB_EXPORT int SbMicrophoneRead(SbMicrophone microphone,
                               void* out_audio_data,
                               int audio_data_size);

// Destroys a microphone. If the microphone is in started state, it will be
// stopped first and then be destroyed. Any data that has been recorded and not
// read will be thrown away.
SB_EXPORT void SbMicrophoneDestroy(SbMicrophone microphone);

#ifdef __cplusplus
}  // extern "C"
#endif

#endif  // SB_HAS(MICROPHONE) && SB_VERSION(2)

#endif  // STARBOARD_MICROPHONE_H_