1 /*
2  *  Copyright (c) 2013 The WebRTC project authors. All Rights Reserved.
3  *
4  *  Use of this source code is governed by a BSD-style license
5  *  that can be found in the LICENSE file in the root of the source
6  *  tree. An additional intellectual property rights grant can be found
7  *  in the file PATENTS.  All contributing project authors may
8  *  be found in the AUTHORS file in the root of the source tree.
9  */
10 
11 #ifndef MODULES_AUDIO_DEVICE_ANDROID_AUDIO_RECORD_JNI_H_
12 #define MODULES_AUDIO_DEVICE_ANDROID_AUDIO_RECORD_JNI_H_
13 
14 #include <jni.h>
15 
16 #include <memory>
17 
18 #include "api/sequence_checker.h"
19 #include "modules/audio_device/android/audio_manager.h"
20 #include "modules/audio_device/audio_device_generic.h"
21 #include "modules/audio_device/include/audio_device_defines.h"
22 #include "modules/utility/include/helpers_android.h"
23 #include "modules/utility/include/jvm_android.h"
24 
25 namespace webrtc {
26 
27 // Implements 16-bit mono PCM audio input support for Android using the Java
28 // AudioRecord interface. Most of the work is done by its Java counterpart in
29 // WebRtcAudioRecord.java. This class is created and lives on a thread in
30 // C++-land, but recorded audio buffers are delivered on a high-priority
31 // thread managed by the Java class.
32 //
33 // The Java class makes use of AudioEffect features (mainly AEC) which are
34 // first available in Jelly Bean. If it is instantiated running against earlier
35 // SDKs, the AEC provided by the APM in WebRTC must be used and enabled
36 // separately instead.
37 //
38 // An instance must be created and destroyed on one and the same thread.
39 // All public methods must also be called on the same thread. A thread checker
40 // will RTC_DCHECK if any method is called on an invalid thread.
41 //
42 // This class uses JvmThreadConnector to attach to a Java VM if needed
43 // and detach when the object goes out of scope. Additional thread checking
44 // guarantees that no other (possibly non attached) thread is used.
45 class AudioRecordJni {
46  public:
47   // Wraps the Java specific parts of the AudioRecordJni into one helper class.
48   class JavaAudioRecord {
49    public:
50     JavaAudioRecord(NativeRegistration* native_registration,
51                     std::unique_ptr<GlobalRef> audio_track);
52     ~JavaAudioRecord();
53 
54     int InitRecording(int sample_rate, size_t channels);
55     bool StartRecording();
56     bool StopRecording();
57     bool EnableBuiltInAEC(bool enable);
58     bool EnableBuiltInNS(bool enable);
59 
60    private:
61     std::unique_ptr<GlobalRef> audio_record_;
62     jmethodID init_recording_;
63     jmethodID start_recording_;
64     jmethodID stop_recording_;
65     jmethodID enable_built_in_aec_;
66     jmethodID enable_built_in_ns_;
67   };
68 
69   explicit AudioRecordJni(AudioManager* audio_manager);
70   ~AudioRecordJni();
71 
72   int32_t Init();
73   int32_t Terminate();
74 
75   int32_t InitRecording();
RecordingIsInitialized()76   bool RecordingIsInitialized() const { return initialized_; }
77 
78   int32_t StartRecording();
79   int32_t StopRecording();
Recording()80   bool Recording() const { return recording_; }
81 
82   void AttachAudioBuffer(AudioDeviceBuffer* audioBuffer);
83 
84   int32_t EnableBuiltInAEC(bool enable);
85   int32_t EnableBuiltInAGC(bool enable);
86   int32_t EnableBuiltInNS(bool enable);
87 
88  private:
89   // Called from Java side so we can cache the address of the Java-manged
90   // |byte_buffer| in |direct_buffer_address_|. The size of the buffer
91   // is also stored in |direct_buffer_capacity_in_bytes_|.
92   // This method will be called by the WebRtcAudioRecord constructor, i.e.,
93   // on the same thread that this object is created on.
94   static void JNICALL CacheDirectBufferAddress(JNIEnv* env,
95                                                jobject obj,
96                                                jobject byte_buffer,
97                                                jlong nativeAudioRecord);
98   void OnCacheDirectBufferAddress(JNIEnv* env, jobject byte_buffer);
99 
100   // Called periodically by the Java based WebRtcAudioRecord object when
101   // recording has started. Each call indicates that there are |length| new
102   // bytes recorded in the memory area |direct_buffer_address_| and it is
103   // now time to send these to the consumer.
104   // This method is called on a high-priority thread from Java. The name of
105   // the thread is 'AudioRecordThread'.
106   static void JNICALL DataIsRecorded(JNIEnv* env,
107                                      jobject obj,
108                                      jint length,
109                                      jlong nativeAudioRecord);
110   void OnDataIsRecorded(int length);
111 
112   // Stores thread ID in constructor.
113   SequenceChecker thread_checker_;
114 
115   // Stores thread ID in first call to OnDataIsRecorded() from high-priority
116   // thread in Java. Detached during construction of this object.
117   SequenceChecker thread_checker_java_;
118 
119   // Calls JavaVM::AttachCurrentThread() if this thread is not attached at
120   // construction.
121   // Also ensures that DetachCurrentThread() is called at destruction.
122   JvmThreadConnector attach_thread_if_needed_;
123 
124   // Wraps the JNI interface pointer and methods associated with it.
125   std::unique_ptr<JNIEnvironment> j_environment_;
126 
127   // Contains factory method for creating the Java object.
128   std::unique_ptr<NativeRegistration> j_native_registration_;
129 
130   // Wraps the Java specific parts of the AudioRecordJni class.
131   std::unique_ptr<AudioRecordJni::JavaAudioRecord> j_audio_record_;
132 
133   // Raw pointer to the audio manger.
134   const AudioManager* audio_manager_;
135 
136   // Contains audio parameters provided to this class at construction by the
137   // AudioManager.
138   const AudioParameters audio_parameters_;
139 
140   // Delay estimate of the total round-trip delay (input + output).
141   // Fixed value set once in AttachAudioBuffer() and it can take one out of two
142   // possible values. See audio_common.h for details.
143   int total_delay_in_milliseconds_;
144 
145   // Cached copy of address to direct audio buffer owned by |j_audio_record_|.
146   void* direct_buffer_address_;
147 
148   // Number of bytes in the direct audio buffer owned by |j_audio_record_|.
149   size_t direct_buffer_capacity_in_bytes_;
150 
151   // Number audio frames per audio buffer. Each audio frame corresponds to
152   // one sample of PCM mono data at 16 bits per sample. Hence, each audio
153   // frame contains 2 bytes (given that the Java layer only supports mono).
154   // Example: 480 for 48000 Hz or 441 for 44100 Hz.
155   size_t frames_per_buffer_;
156 
157   bool initialized_;
158 
159   bool recording_;
160 
161   // Raw pointer handle provided to us in AttachAudioBuffer(). Owned by the
162   // AudioDeviceModuleImpl class and called by AudioDeviceModule::Create().
163   AudioDeviceBuffer* audio_device_buffer_;
164 };
165 
166 }  // namespace webrtc
167 
168 #endif  // MODULES_AUDIO_DEVICE_ANDROID_AUDIO_RECORD_JNI_H_
169