1 /* -*- Mode: C++; tab-width: 2; indent-tabs-mode: nil; c-basic-offset: 2 -*- */
2 /* vim:set ts=2 sw=2 sts=2 et cindent: */
3 /* This Source Code Form is subject to the terms of the Mozilla Public
4 * License, v. 2.0. If a copy of the MPL was not distributed with this
5 * file, You can obtain one at http://mozilla.org/MPL/2.0/. */
6 #if !defined(AudioStream_h_)
7 # define AudioStream_h_
9 # include "AudioSampleFormat.h"
10 # include "CubebUtils.h"
11 # include "MediaInfo.h"
12 # include "MediaSink.h"
13 # include "mozilla/Atomics.h"
14 # include "mozilla/Monitor.h"
15 # include "mozilla/MozPromise.h"
16 # include "mozilla/ProfilerUtils.h"
17 # include "mozilla/RefPtr.h"
18 # include "mozilla/Result.h"
19 # include "mozilla/TimeStamp.h"
20 # include "mozilla/UniquePtr.h"
21 # include "mozilla/SPSCQueue.h"
22 # include "nsCOMPtr.h"
23 # include "nsThreadUtils.h"
24 # include "WavDumper.h"
28 struct CubebDestroyPolicy
{
29 void operator()(cubeb_stream
* aStream
) const {
30 cubeb_stream_destroy(aStream
);
37 class RLBoxSoundTouch
;
39 // A struct that contains the number of frames serviced or underrun by a
40 // callback, alongside the sample-rate for this callback (in case of playback
41 // rate change, it can be variable).
43 CallbackInfo() = default;
44 CallbackInfo(uint32_t aServiced
, uint32_t aUnderrun
, uint32_t aOutputRate
)
45 : mServiced(aServiced
), mUnderrun(aUnderrun
), mOutputRate(aOutputRate
) {}
46 uint32_t mServiced
= 0;
47 uint32_t mUnderrun
= 0;
48 uint32_t mOutputRate
= 0;
53 explicit AudioClock(uint32_t aInRate
);
55 // Update the number of samples that has been written in the audio backend.
56 // Called on the audio thread only.
57 void UpdateFrameHistory(uint32_t aServiced
, uint32_t aUnderrun
,
58 bool aAudioThreadChanged
);
61 * @param aFrames The playback position in frames of the audio engine.
62 * @return The playback position in frames of the stream,
63 * adjusted by playback rate changes and underrun frames.
65 int64_t GetPositionInFrames(int64_t aFrames
);
68 * @param frames The playback position in frames of the audio engine.
69 * @return The playback position in microseconds of the stream,
70 * adjusted by playback rate changes and underrun frames.
72 int64_t GetPosition(int64_t frames
);
74 // Set the playback rate.
75 // Called on the audio thread only.
76 void SetPlaybackRate(double aPlaybackRate
);
77 // Get the current playback rate.
78 // Called on the audio thread only.
79 double GetPlaybackRate() const;
80 // Set if we are preserving the pitch.
81 // Called on the audio thread only.
82 void SetPreservesPitch(bool aPreservesPitch
);
83 // Get the current pitch preservation state.
84 // Called on the audio thread only.
85 bool GetPreservesPitch() const;
87 // Called on either thread.
88 uint32_t GetInputRate() const { return mInRate
; }
89 uint32_t GetOutputRate() const { return mOutRate
; }
92 // Output rate in Hz (characteristic of the playback rate). Written on the
93 // audio thread, read on either thread.
94 Atomic
<uint32_t> mOutRate
;
95 // Input rate in Hz (characteristic of the media being played).
96 const uint32_t mInRate
;
97 // True if the we are timestretching, false if we are resampling. Accessed on
98 // the audio thread only.
100 // The history of frames sent to the audio engine in each DataCallback.
101 // Only accessed from non-audio threads on macOS, accessed on both threads and
102 // protected by the AudioStream monitor on other platforms.
103 const UniquePtr
<FrameHistory
> mFrameHistory
105 MOZ_GUARDED_BY(mMutex
)
109 // Enqueued on the audio thread, dequeued from the other thread. The maximum
110 // size of this queue has been chosen empirically.
111 SPSCQueue
<CallbackInfo
> mCallbackInfoQueue
{100};
112 // If it isn't possible to send the callback info to the non-audio thread,
113 // store them here until it's possible to send them. This is an unlikely
114 // fallback path. The size of this array has been chosen empirically. Only
115 // ever accessed on the audio thread.
116 AutoTArray
<CallbackInfo
, 5> mAudioThreadCallbackInfo
;
118 Mutex mMutex
{"AudioClock"};
123 * A bookkeeping class to track the read/write position of an audio buffer.
125 class AudioBufferCursor
{
127 AudioBufferCursor(Span
<AudioDataValue
> aSpan
, uint32_t aChannels
,
129 : mChannels(aChannels
), mSpan(aSpan
), mFrames(aFrames
) {}
131 // Advance the cursor to account for frames that are consumed.
132 uint32_t Advance(uint32_t aFrames
) {
133 MOZ_DIAGNOSTIC_ASSERT(Contains(aFrames
));
134 MOZ_ASSERT(mFrames
>= aFrames
);
136 mOffset
+= mChannels
* aFrames
;
140 // The number of frames available for read/write in this buffer.
141 uint32_t Available() const { return mFrames
; }
143 // Return a pointer where read/write should begin.
144 AudioDataValue
* Ptr() const {
145 MOZ_DIAGNOSTIC_ASSERT(mOffset
<= mSpan
.Length());
146 return mSpan
.Elements() + mOffset
;
150 bool Contains(uint32_t aFrames
) const {
151 return mSpan
.Length() >= mOffset
+ mChannels
* aFrames
;
153 const uint32_t mChannels
;
156 const Span
<AudioDataValue
> mSpan
;
162 * A helper class to encapsulate pointer arithmetic and provide means to modify
163 * the underlying audio buffer.
165 class AudioBufferWriter
: public AudioBufferCursor
{
167 AudioBufferWriter(Span
<AudioDataValue
> aSpan
, uint32_t aChannels
,
169 : AudioBufferCursor(aSpan
, aChannels
, aFrames
) {}
171 uint32_t WriteZeros(uint32_t aFrames
) {
172 MOZ_DIAGNOSTIC_ASSERT(Contains(aFrames
));
173 memset(Ptr(), 0, sizeof(AudioDataValue
) * mChannels
* aFrames
);
174 return Advance(aFrames
);
177 uint32_t Write(const AudioDataValue
* aPtr
, uint32_t aFrames
) {
178 MOZ_DIAGNOSTIC_ASSERT(Contains(aFrames
));
179 memcpy(Ptr(), aPtr
, sizeof(AudioDataValue
) * mChannels
* aFrames
);
180 return Advance(aFrames
);
183 // Provide a write fuction to update the audio buffer with the following
184 // signature: uint32_t(const AudioDataValue* aPtr, uint32_t aFrames)
185 // aPtr: Pointer to the audio buffer.
186 // aFrames: The number of frames available in the buffer.
187 // return: The number of frames actually written by the function.
188 template <typename Function
>
189 uint32_t Write(const Function
& aFunction
, uint32_t aFrames
) {
190 MOZ_DIAGNOSTIC_ASSERT(Contains(aFrames
));
191 return Advance(aFunction(Ptr(), aFrames
));
194 using AudioBufferCursor::Available
;
197 // Access to a single instance of this class must be synchronized by
198 // callers, or made from a single thread. One exception is that access to
199 // GetPosition, GetPositionInFrames, SetVolume, and Get{Rate,Channels},
200 // SetMicrophoneActive is thread-safe without external synchronization.
201 class AudioStream final
{
202 virtual ~AudioStream();
205 NS_INLINE_DECL_THREADSAFE_REFCOUNTING(AudioStream
)
209 // Return a pointer to the audio data.
210 virtual const AudioDataValue
* Data() const = 0;
211 // Return the number of frames in this chunk.
212 virtual uint32_t Frames() const = 0;
213 // Return the number of audio channels.
214 virtual uint32_t Channels() const = 0;
215 // Return the sample rate of this chunk.
216 virtual uint32_t Rate() const = 0;
217 // Return a writable pointer for downmixing.
218 virtual AudioDataValue
* GetWritable() const = 0;
219 virtual ~Chunk() = default;
224 // Attempt to acquire aFrames frames of audio, and returns the number of
225 // frames successfuly acquired.
226 virtual uint32_t PopFrames(AudioDataValue
* aAudio
, uint32_t aFrames
,
227 bool aAudioThreadChanged
) = 0;
228 // Return true if no more data will be added to the source.
229 virtual bool Ended() const = 0;
232 virtual ~DataSource() = default;
235 // aOutputChannels is the number of audio channels (1 for mono, 2 for stereo,
236 // etc), aChannelMap is the indicator for channel layout(mono, stereo, 5.1 or
237 // 7.1 ). Initialize the audio stream.and aRate is the sample rate
238 // (22050Hz, 44100Hz, etc).
239 AudioStream(DataSource
& aSource
, uint32_t aInRate
, uint32_t aOutputChannels
,
240 AudioConfig::ChannelLayout::ChannelMap aChannelMap
);
242 nsresult
Init(AudioDeviceInfo
* aSinkInfo
);
244 // Closes the stream. All future use of the stream is an error.
247 // Set the current volume of the audio playback. This is a value from
248 // 0 (meaning muted) to 1 (meaning full volume). Thread-safe.
249 void SetVolume(double aVolume
);
251 void SetStreamName(const nsAString
& aStreamName
);
254 RefPtr
<MediaSink::EndedPromise
> Start();
256 // Pause audio playback.
259 // Resume audio playback.
262 // Return the position in microseconds of the audio frame being played by
263 // the audio hardware, compensated for playback rate change. Thread-safe.
264 int64_t GetPosition();
266 // Return the position, measured in audio frames played since the stream
267 // was opened, of the audio hardware. Thread-safe.
268 int64_t GetPositionInFrames();
270 uint32_t GetOutChannels() const { return mOutChannels
; }
272 // Set playback rate as a multiple of the intrinsic playback rate. This is
273 // to be called only with aPlaybackRate > 0.0.
274 nsresult
SetPlaybackRate(double aPlaybackRate
);
275 // Switch between resampling (if false) and time stretching (if true,
277 nsresult
SetPreservesPitch(bool aPreservesPitch
);
279 size_t SizeOfIncludingThis(MallocSizeOf aMallocSizeOf
) const;
281 bool IsPlaybackCompleted() const;
283 // Returns true if at least one DataCallback has been called.
284 bool CallbackStarted() const { return mCallbacksStarted
; }
287 friend class AudioClock
;
289 // Return the position, measured in audio frames played since the stream was
290 // opened, of the audio hardware, not adjusted for the changes of playback
291 // rate or underrun frames.
292 // Caller must own the monitor.
293 int64_t GetPositionInFramesUnlocked();
296 nsresult
OpenCubeb(cubeb
* aContext
, cubeb_stream_params
& aParams
,
297 TimeStamp aStartTime
, bool aIsFirst
);
299 static long DataCallback_S(cubeb_stream
*, void* aThis
,
300 const void* /* aInputBuffer */,
301 void* aOutputBuffer
, long aFrames
) {
302 return static_cast<AudioStream
*>(aThis
)->DataCallback(aOutputBuffer
,
306 static void StateCallback_S(cubeb_stream
*, void* aThis
, cubeb_state aState
) {
307 static_cast<AudioStream
*>(aThis
)->StateCallback(aState
);
310 long DataCallback(void* aBuffer
, long aFrames
);
311 void StateCallback(cubeb_state aState
);
314 nsresult
EnsureTimeStretcherInitialized();
315 void GetUnprocessed(AudioBufferWriter
& aWriter
);
316 void GetTimeStretched(AudioBufferWriter
& aWriter
);
317 void UpdatePlaybackRateIfNeeded();
319 // Return true if audio frames are valid (correct sampling rate and valid
320 // channel count) otherwise false.
321 bool IsValidAudioFormat(Chunk
* aChunk
) MOZ_REQUIRES(mMonitor
);
323 template <typename Function
, typename
... Args
>
324 int InvokeCubeb(Function aFunction
, Args
&&... aArgs
) MOZ_REQUIRES(mMonitor
);
325 bool CheckThreadIdChanged();
326 void AssertIsOnAudioThread() const;
328 RLBoxSoundTouch
* mTimeStretcher
;
329 AudioClock mAudioClock
;
333 const AudioConfig::ChannelLayout::ChannelMap mChannelMap
;
335 // The monitor is held to protect all access to member variables below.
336 Monitor mMonitor MOZ_UNANNOTATED
;
338 const uint32_t mOutChannels
;
340 // mCubebStream holds a bare pointer to cubeb, so we hold a ref on its behalf
341 RefPtr
<CubebUtils::CubebHandle
> mCubeb
;
342 // Owning reference to a cubeb_stream. Set in Init(), cleared in ShutDown, so
343 // no lock is needed to access.
344 UniquePtr
<cubeb_stream
, CubebDestroyPolicy
> mCubebStream
;
347 INITIALIZED
, // Initialized, playback has not begun.
348 STARTED
, // cubeb started.
349 STOPPED
, // Stopped by a call to Pause().
350 DRAINED
, // StateCallback has indicated that the drain is complete.
351 ERRORED
, // Stream disabled due to an internal error.
352 SHUTDOWN
// ShutDown has been called
355 std::atomic
<StreamState
> mState
;
357 // DataSource::PopFrames can never be called concurrently.
358 // DataSource::IsEnded uses only atomics.
359 DataSource
& mDataSource
;
361 // The device info of the current sink. If null
362 // the default device is used. It is set
363 // during the Init() in decoder thread.
364 RefPtr
<AudioDeviceInfo
> mSinkInfo
;
365 // Contains the id of the audio thread, from profiler_get_thread_id.
366 std::atomic
<ProfilerThreadId
> mAudioThreadId
;
367 const bool mSandboxed
= false;
369 MozPromiseHolder
<MediaSink::EndedPromise
> mEndedPromise
370 MOZ_GUARDED_BY(mMonitor
);
371 std::atomic
<bool> mPlaybackComplete
;
372 // Both written on the MDSM thread, read on the audio thread.
373 std::atomic
<float> mPlaybackRate
;
374 std::atomic
<bool> mPreservesPitch
;
376 bool mAudioThreadChanged
= false;
377 Atomic
<bool> mCallbacksStarted
;
380 } // namespace mozilla