Add new P functions, setUsage() etc

AAudioStreamBuilder_setInputPreset()
    _setContentType()
    _setSessionID()

Fixes #78

include/oboe/AudioStreamBase.h

@@ -94,6 +94,14 @@ class AudioStreamBase {
         return mStreamCallback;
     }
 
+    Usage getUsage() const { return mUsage; }
+
+    ContentType getContentType() const { return mContentType; }
+
+    InputPreset getInputPreset() const { return mInputPreset; }
+
+    SessionId getSessionId() const { return mSessionId; }
+
 protected:
     AudioStreamCallback            *mStreamCallback = nullptr;
     int32_t                         mFramesPerCallback = kUnspecified;
@@ -106,6 +114,11 @@ class AudioStreamBase {
     AudioFormat                     mFormat = AudioFormat::Unspecified;
     Direction                       mDirection = Direction::Output;
     PerformanceMode                 mPerformanceMode = PerformanceMode::None;
+    // Added in API 28
+    Usage                           mUsage = Usage::Media;
+    ContentType                     mContentType = ContentType::Music;
+    InputPreset                     mInputPreset = InputPreset::VoiceRecognition;
+    SessionId                       mSessionId = SessionId::None;
 };
 
 } // namespace oboe

include/oboe/AudioStreamBuilder.h

@@ -173,6 +173,90 @@ class AudioStreamBuilder : public AudioStreamBase {
         return this;
     }
 
+
+    /**
+     * Set the intended use case for the stream.
+     *
+     * The system will use this information to optimize the behavior of the stream.
+     * This could, for example, affect how volume and focus is handled for the stream.
+     *
+     * The default, if you do not call this function, is Usage::Media.
+     *
+     * Added in API level 28.
+     *
+     * @param usage the desired usage, eg. Usage::Game
+     */
+    AudioStreamBuilder *setUsage(Usage usage) {
+        mUsage = usage;
+        return this;
+    }
+
+    /**
+     * Set the type of audio data that the stream will carry.
+     *
+     * The system will use this information to optimize the behavior of the stream.
+     * This could, for example, affect whether a stream is paused when a notification occurs.
+     *
+     * The default, if you do not call this function, is ContentType::Music.
+     *
+     * Added in API level 28.
+     *
+     * @param contentType the type of audio data, eg. ContentType::Speech
+     */
+    AudioStreamBuilder *setContentType(ContentType contentType) {
+        mContentType = contentType;
+        return this;
+    }
+
+    /**
+     * Set the input (capture) preset for the stream.
+     *
+     * The system will use this information to optimize the behavior of the stream.
+     * This could, for example, affect which microphones are used and how the
+     * recorded data is processed.
+     *
+     * The default, if you do not call this function, is InputPreset::VoiceRecognition.
+     * That is because VoiceRecognition is the preset with the lowest latency
+     * on many platforms.
+     *
+     * Added in API level 28.
+     *
+     * @param inputPreset the desired configuration for recording
+     */
+    AudioStreamBuilder *setInputPreset(InputPreset inputPreset) {
+        mInputPreset = inputPreset;
+        return this;
+    }
+
+    /** Set the requested session ID.
+     *
+     * The session ID can be used to associate a stream with effects processors.
+     * The effects are controlled using the Android AudioEffect Java API.
+     *
+     * The default, if you do not call this function, is SessionId::None.
+     *
+     * If set to SessionId::Allocate then a session ID will be allocated
+     * when the stream is opened.
+     *
+     * The allocated session ID can be obtained by calling AudioStream::getSessionId()
+     * and then used with this function when opening another stream.
+     * This allows effects to be shared between streams.
+     *
+     * Session IDs from Oboe can be used the Android Java APIs and vice versa.
+     * So a session ID from an Oboe stream can be passed to Java
+     * and effects applied using the Java AudioEffect API.
+     *
+     * Allocated session IDs will always be positive and nonzero.
+     *
+     * Added in API level 28.
+     *
+     * @param sessionId an allocated sessionID or SessionId::Allocate
+     */
+    AudioStreamBuilder *setSessionId(SessionId sessionId) {
+        mSessionId = sessionId;
+        return this;
+    }
+
     /**
      * Request an audio device identified device using an ID.
      * On Android, for example, the ID could be obtained from the Java AudioManager.

include/oboe/Definitions.h

@@ -143,6 +143,175 @@ namespace oboe {
         AAudio
     };
 
+    /**
+     * The Usage attribute expresses "why" you are playing a sound, what is this sound used for.
+     * This information is used by certain platforms or routing policies
+     * to make more refined volume or routing decisions.
+     *
+     * Note that these match the equivalent values in AudioAttributes in the Android Java API.
+     *
+     * Added in API level 28.
+     */
+    enum class Usage : aaudio_usage_t {
+        /**
+         * Use this for streaming media, music performance, video, podcasts, etcetera.
+         */
+        Media = AAUDIO_USAGE_MEDIA,
+
+        /**
+         * Use this for voice over IP, telephony, etcetera.
+         */
+        VoiceCommunication = AAUDIO_USAGE_VOICE_COMMUNICATION,
+
+        /**
+         * Use this for sounds associated with telephony such as busy tones, DTMF, etcetera.
+         */
+        VoiceCommunicationSignalling = AAUDIO_USAGE_VOICE_COMMUNICATION_SIGNALLING,
+
+        /**
+         * Use this to demand the users attention.
+         */
+        Alarm = AAUDIO_USAGE_ALARM,
+
+        /**
+         * Use this for notifying the user when a message has arrived or some
+         * other background event has occured.
+         */
+        Notification = AAUDIO_USAGE_NOTIFICATION,
+
+        /**
+         * Use this when the phone rings.
+         */
+        NotificationRingtone = AAUDIO_USAGE_NOTIFICATION_RINGTONE,
+
+        /**
+         * Use this to attract the users attention when, for example, the battery is low.
+         */
+        NotificationEvent = AAUDIO_USAGE_NOTIFICATION_EVENT,
+
+        /**
+         * Use this for screen readers, etcetera.
+         */
+        AssistanceAccessibility = AAUDIO_USAGE_ASSISTANCE_ACCESSIBILITY,
+
+        /**
+         * Use this for driving or navigation directions.
+         */
+        AssistanceNavigationGuidance = AAUDIO_USAGE_ASSISTANCE_NAVIGATION_GUIDANCE,
+
+        /**
+         * Use this for user interface sounds, beeps, etcetera.
+         */
+        AssistanceSonification = AAUDIO_USAGE_ASSISTANCE_SONIFICATION,
+
+        /**
+         * Use this for game audio and sound effects.
+         */
+        Game = AAUDIO_USAGE_GAME,
+
+        /**
+         * Use this for audio responses to user queries, audio instructions or help utterances.
+         */
+        Assistant = AAUDIO_USAGE_ASSISTANT,
+    };
+
+
+    /**
+     * The CONTENT_TYPE attribute describes "what" you are playing.
+     * It expresses the general category of the content. This information is optional.
+     * But in case it is known (for instance {@link #AAUDIO_CONTENT_TYPE_MOVIE} for a
+     * movie streaming service or {@link #AAUDIO_CONTENT_TYPE_SPEECH} for
+     * an audio book application) this information might be used by the audio framework to
+     * enforce audio focus.
+     *
+     * Note that these match the equivalent values in AudioAttributes in the Android Java API.
+     *
+     * Added in API level 28.
+     */
+    enum ContentType : aaudio_content_type_t {
+
+        /**
+         * Use this for spoken voice, audio books, etcetera.
+         */
+        Speech = AAUDIO_CONTENT_TYPE_SPEECH,
+
+        /**
+         * Use this for pre-recorded or live music.
+         */
+        Music = AAUDIO_CONTENT_TYPE_MUSIC,
+
+        /**
+         * Use this for a movie or video soundtrack.
+         */
+        Movie = AAUDIO_CONTENT_TYPE_MOVIE,
+
+        /**
+         * Use this for sound is designed to accompany a user action,
+         * such as a click or beep sound made when the user presses a button.
+         */
+        Sonification = AAUDIO_CONTENT_TYPE_SONIFICATION,
+    };
+
+    /**
+     * Defines the audio source.
+     * An audio source defines both a default physical source of audio signal, and a recording
+     * configuration.
+     *
+     * Note that these match the equivalent values in MediaRecorder.AudioSource in the Android Java API.
+     *
+     * Added in API level 28.
+     */
+    enum InputPreset : aaudio_input_preset_t {
+        /**
+         * Use this preset when other presets do not apply.
+         */
+        Generic = AAUDIO_INPUT_PRESET_GENERIC,
+
+        /**
+         * Use this preset when recording video.
+         */
+        Camcorder = AAUDIO_INPUT_PRESET_CAMCORDER,
+
+        /**
+         * Use this preset when doing speech recognition.
+         */
+        VoiceRecognition = AAUDIO_INPUT_PRESET_VOICE_RECOGNITION,
+
+        /**
+         * Use this preset when doing telephony or voice messaging.
+         */
+        VoiceCommunication = AAUDIO_INPUT_PRESET_VOICE_COMMUNICATION,
+
+        /**
+         * Use this preset to obtain an input with no effects.
+         * Note that this input will not have automatic gain control
+         * so the recorded volume may be very low.
+         */
+        Unprocessed = AAUDIO_INPUT_PRESET_UNPROCESSED,
+    };
+
+    enum SessionId {
+        /**
+         * Do not allocate a session ID.
+         * Effects cannot be used with this stream.
+         * Default.
+         *
+         * Added in API level 28.
+         */
+         None = AAUDIO_SESSION_ID_NONE,
+
+        /**
+         * Allocate a session ID that can be used to attach and control
+         * effects using the Java AudioEffects API.
+         * Note that the use of this flag may result in higher latency.
+         *
+         * Note that this matches the value of AudioManager.AUDIO_SESSION_ID_GENERATE.
+         *
+         * Added in API level 28.
+         */
+         Allocate = AAUDIO_SESSION_ID_ALLOCATE,
+    };
+
 } // namespace oboe
 
 #endif // OBOE_DEFINITIONS_H

src/aaudio/AAudioLoader.cpp

@@ -63,9 +63,14 @@ int AAudioLoader::open() {
     builder_setFormat          = load_V_PBI("AAudioStreamBuilder_setFormat");
     builder_setFramesPerDataCallback = load_V_PBI("AAudioStreamBuilder_setFramesPerDataCallback");
     builder_setSharingMode     = load_V_PBI("AAudioStreamBuilder_setSharingMode");
-    builder_setPerformanceMode     = load_V_PBI("AAudioStreamBuilder_setPerformanceMode");
+    builder_setPerformanceMode = load_V_PBI("AAudioStreamBuilder_setPerformanceMode");
     builder_setSampleRate      = load_V_PBI("AAudioStreamBuilder_setSampleRate");
 
+    builder_setUsage           = load_V_PBI("AAudioStreamBuilder_setUsage");
+    builder_setContentType     = load_V_PBI("AAudioStreamBuilder_setContentType");
+    builder_setInputPreset     = load_V_PBI("AAudioStreamBuilder_setinputPreset");
+    builder_setSessionId       = load_V_PBI("AAudioStreamBuilder_setSessionId");
+
     builder_delete             = load_I_PB("AAudioStreamBuilder_delete");
 
     stream_getFormat = (aaudio_format_t (*)(AAudioStream *stream))
@@ -138,6 +143,11 @@ int AAudioLoader::open() {
     convertResultToText       = load_PC_I("AAudio_convertResultToText");
     convertStreamStateToText  = load_PC_I("AAudio_convertStreamStateToText");
 
+    stream_getUsage           = load_I_PS("AAudioStream_getUsage");
+    stream_getContentType     = load_I_PS("AAudioStream_getContentType");
+    stream_getInputPreset     = load_I_PS("AAudioStream_getInputPreset");
+    stream_getSessionId       = load_I_PS("AAudioStream_getSessionId");
+
     return 0;
 }
 

src/aaudio/AAudioLoader.h

@@ -86,6 +86,11 @@ class AAudioLoader {
     signature_V_PBI builder_setSampleRate;
     signature_V_PBI builder_setSharingMode;
 
+    signature_V_PBI builder_setUsage;
+    signature_V_PBI builder_setContentType;
+    signature_V_PBI builder_setInputPreset;
+    signature_V_PBI builder_setSessionId;
+
     void (*builder_setDataCallback)(AAudioStreamBuilder *builder,
                                     AAudioStream_dataCallback callback,
                                     void *userData);
@@ -144,7 +149,10 @@ class AAudioLoader {
     signature_PC_I   convertResultToText;
     signature_PC_I   convertStreamStateToText;
 
-    // TODO add any missing AAudio functions.
+    signature_I_PS   stream_getUsage;
+    signature_I_PS   stream_getContentType;
+    signature_I_PS   stream_getInputPreset;
+    signature_I_PS   stream_getSessionId;
 
   private:
     AAudioLoader() {}