blob: 82d2690e2965c05514e0b95366bf7b484d91bb81 [file] [log] [blame]
/*
* Copyright (C) 2019 The Android Open Source Project
*
* 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.
*/
#pragma once
#include "Sound.h"
#include <audio_utils/clock.h>
#include <media/AudioTrack.h>
namespace android::soundpool {
// This is the amount of time to wait after stop is called when stealing an
// AudioTrack to allow the sound to ramp down. If this is 0, glitches
// may occur when stealing an AudioTrack.
inline constexpr int64_t kStopWaitTimeNs = 20 * NANOS_PER_MILLISECOND;
inline constexpr size_t kCacheLineSize = 64; /* std::hardware_constructive_interference_size */
class StreamManager; // forward decl
/**
* A Stream is associated with a StreamID exposed to the app to play a Sound.
*
* The Stream uses monitor locking strategy on mLock.
* https://en.wikipedia.org/wiki/Monitor_(synchronization)
*
* where public methods are guarded by a lock (as needed)
*
* For Java equivalent APIs, see
* https://developer.android.com/reference/android/media/SoundPool
*
* Streams are paired by the StreamManager, so one stream in the pair may be "stopping"
* while the other stream of the pair has been prepared to run
* (and the streamID returned to the app) pending its pair to be stopped.
* The pair of a Stream may be obtained by calling getPairStream(),
* where this->getPairStream()->getPairStream() == this; (pair is a commutative relationship).
*
* playPairStream() and getPairPriority() access the paired stream.
* See also StreamManager.h for details of physical layout implications of paired streams.
*/
class alignas(kCacheLineSize) Stream {
public:
enum state { IDLE, PAUSED, PLAYING };
// The PAUSED, PLAYING state directly corresponds to the AudioTrack state of an active Stream.
//
// The IDLE state indicates an inactive Stream. An IDLE Stream may have a non-nullptr
// AudioTrack, which may be recycled for use if the SoundID matches the next Stream playback.
//
// PAUSED -> PLAYING through resume() (see also autoResume())
// PLAYING -> PAUSED through pause() (see also autoPause())
//
// IDLE is the initial state of a Stream and also when a stream becomes inactive.
// {PAUSED, PLAYING} -> IDLE through stop() (or if the Sound finishes playing)
// IDLE -> PLAYING through play(). (there is no way to start a Stream in paused mode).
~Stream();
void setStreamManager(StreamManager* streamManager) { // non-nullptr
mStreamManager = streamManager; // set in StreamManager constructor, not changed
}
// The following methods are monitor locked by mLock.
//
// For methods taking a streamID:
// if the streamID matches the Stream's mStreamID, then method proceeds
// else the command is ignored with no effect.
// returns true if the stream needs to be explicitly stopped.
bool requestStop(int32_t streamID);
void stop(); // explicit stop(), typically called from the worker thread.
void clearAudioTrack();
void pause(int32_t streamID);
void autoPause(); // see the Java SoundPool.autoPause documentation for details.
void resume(int32_t streamID);
void autoResume();
void mute(bool muting);
void dump() const;
// returns the pair stream if successful, nullptr otherwise
Stream* playPairStream();
// These parameters are explicitly checked in the SoundPool class
// so never deviate from the Java API specified values.
void setVolume(int32_t streamID, float leftVolume, float rightVolume);
void setRate(int32_t streamID, float rate);
void setPriority(int32_t streamID, int priority);
void setLoop(int32_t streamID, int loop);
void setPlay(int32_t streamID, const std::shared_ptr<Sound> &sound, int32_t soundID,
float leftVolume, float rightVolume, int32_t priority, int32_t loop, float rate);
void setStopTimeNs(int64_t stopTimeNs); // systemTime() clock monotonic.
// The following getters are not locked and have weak consistency.
// These are considered advisory only - being stale is of nuisance.
int32_t getPriority() const { return mPriority; }
int32_t getPairPriority() const { return getPairStream()->getPriority(); }
int64_t getStopTimeNs() const { return mStopTimeNs; }
int32_t getStreamID() const { return mStreamID; } // Can change with setPlay()
int32_t getSoundID() const { return mSoundID; } // Can change with play_l()
bool hasSound() const { return mSound.get() != nullptr; }
Stream* getPairStream() const; // this never changes. See top of header.
private:
void play_l(const std::shared_ptr<Sound>& sound, int streamID,
float leftVolume, float rightVolume, int priority, int loop, float rate,
sp<AudioTrack> releaseTracks[2]);
void stop_l();
void setVolume_l(float leftVolume, float rightVolume);
// For use with AudioTrack callback.
static void staticCallback(int event, void* user, void* info);
void callback(int event, void* info, int toggle, int tries);
// StreamManager should be set on construction and not changed.
// release mLock before calling into StreamManager
StreamManager* mStreamManager = nullptr;
mutable std::mutex mLock;
std::atomic_int32_t mStreamID = 0; // Note: valid streamIDs are always positive.
int mState = IDLE;
std::shared_ptr<Sound> mSound; // Non-null if playing.
int32_t mSoundID = 0; // The sound ID associated with the AudioTrack.
float mLeftVolume = 0.f;
float mRightVolume = 0.f;
int32_t mPriority = INT32_MIN;
int32_t mLoop = 0;
float mRate = 0.f;
bool mAutoPaused = false;
bool mMuted = false;
sp<AudioTrack> mAudioTrack;
int mToggle = 0;
int64_t mStopTimeNs = 0; // if nonzero, time to wait for stop.
};
} // namespace android::soundpool