starboard/microphone.h - cobalt - Git at Google

 // Copyright 2016 The Cobalt Authors. 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.

 // Module Overview: Starboard Microphone module
 //
 // 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.
 // 2. Create a supported microphone, using |SbMicrophoneCreate|, with enough
 //    buffer size and sample rate. Use |SbMicrophoneIsSampleRateSupported| to
 //    verify the sample rate.
 // 3. Use |SbMicrophoneOpen| to open the microphone port and start recording
 //    audio data.
 // 4. Periodically read out the data from microphone with |SbMicrophoneRead|.
 // 5. Call |SbMicrophoneClose| to close the microphone port and stop recording
 //    audio data.
 // 6. Destroy the microphone with |SbMicrophoneDestroy|.

 #ifndef STARBOARD_MICROPHONE_H_
 #define STARBOARD_MICROPHONE_H_

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

 #define kSbMicrophoneLabelSize 256

 #ifdef __cplusplus
 extern "C" {
 #endif

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

   // Microphone in the headset that can be a wired or wireless USB headset.
   kSbMicrophoneUSBHeadset,

   // Microphone in the VR headset.
   kSbMicrophoneVRHeadset,

   // Microphone in the analog headset.
   kSBMicrophoneAnalogHeadset,

   // Unknown microphone type. The microphone could be different than the other
   // enum descriptions or could fall under one of those descriptions.
   kSbMicrophoneUnknown,
 } SbMicrophoneType;

 // An opaque handle to an implementation-private structure that represents a
 // microphone ID.
 typedef struct SbMicrophoneIdPrivate* SbMicrophoneId;

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

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

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

   // Microphone type.
   SbMicrophoneType type;

   // The microphone's maximum supported sampling rate.
   int max_sample_rate_hz;

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

   // 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.
   char label[kSbMicrophoneLabelSize];
 } SbMicrophoneInfo;

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

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

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

 // 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|.
 SB_EXPORT int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array,
                                        int info_array_size);

 // Indicates whether the microphone supports the sample rate.
 SB_EXPORT bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id,
                                                  int sample_rate_in_hz);

 // 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|.
 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 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.
 SB_EXPORT bool SbMicrophoneOpen(SbMicrophone microphone);

 // 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.
 SB_EXPORT bool SbMicrophoneClose(SbMicrophone microphone);

 // 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.
 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 is first
 // stopped and then destroyed. Any data that has been recorded and not read
 // is thrown away.
 SB_EXPORT void SbMicrophoneDestroy(SbMicrophone microphone);

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

 #endif  // STARBOARD_MICROPHONE_H_
	// Copyright 2016 The Cobalt Authors. 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.

	// Module Overview: Starboard Microphone module
	//
	// 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.
	// 2. Create a supported microphone, using \|SbMicrophoneCreate\|, with enough
	// buffer size and sample rate. Use \|SbMicrophoneIsSampleRateSupported\| to
	// verify the sample rate.
	// 3. Use \|SbMicrophoneOpen\| to open the microphone port and start recording
	// audio data.
	// 4. Periodically read out the data from microphone with \|SbMicrophoneRead\|.
	// 5. Call \|SbMicrophoneClose\| to close the microphone port and stop recording
	// audio data.
	// 6. Destroy the microphone with \|SbMicrophoneDestroy\|.

	#ifndef STARBOARD_MICROPHONE_H_
	#define STARBOARD_MICROPHONE_H_

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

	#define kSbMicrophoneLabelSize 256

	#ifdef __cplusplus
	extern "C" {
	#endif

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

	// Microphone in the headset that can be a wired or wireless USB headset.
	kSbMicrophoneUSBHeadset,

	// Microphone in the VR headset.
	kSbMicrophoneVRHeadset,

	// Microphone in the analog headset.
	kSBMicrophoneAnalogHeadset,

	// Unknown microphone type. The microphone could be different than the other
	// enum descriptions or could fall under one of those descriptions.
	kSbMicrophoneUnknown,
	} SbMicrophoneType;

	// An opaque handle to an implementation-private structure that represents a
	// microphone ID.
	typedef struct SbMicrophoneIdPrivate* SbMicrophoneId;

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

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

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

	// Microphone type.
	SbMicrophoneType type;

	// The microphone's maximum supported sampling rate.
	int max_sample_rate_hz;

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

	// 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.
	char label[kSbMicrophoneLabelSize];
	} SbMicrophoneInfo;

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

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

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

	// 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\|.
	SB_EXPORT int SbMicrophoneGetAvailable(SbMicrophoneInfo* out_info_array,
	int info_array_size);

	// Indicates whether the microphone supports the sample rate.
	SB_EXPORT bool SbMicrophoneIsSampleRateSupported(SbMicrophoneId id,
	int sample_rate_in_hz);

	// 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\|.
	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 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.
	SB_EXPORT bool SbMicrophoneOpen(SbMicrophone microphone);

	// 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.
	SB_EXPORT bool SbMicrophoneClose(SbMicrophone microphone);

	// 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.
	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 is first
	// stopped and then destroyed. Any data that has been recorded and not read
	// is thrown away.
	SB_EXPORT void SbMicrophoneDestroy(SbMicrophone microphone);

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

	#endif // STARBOARD_MICROPHONE_H_