1/*
2 * Copyright (C) 2011 The Android Open Source Project
3 *
4 * Licensed under the Apache License, Version 2.0 (the "License");
5 * you may not use this file except in compliance with the License.
6 * You may obtain a copy of the License at
7 *
8 *      http://www.apache.org/licenses/LICENSE-2.0
9 *
10 * Unless required by applicable law or agreed to in writing, software
11 * distributed under the License is distributed on an "AS IS" BASIS,
12 * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
13 * See the License for the specific language governing permissions and
14 * limitations under the License.
15 */
16
17#ifndef __ANDROID_GENERICPLAYER_H__
18#define __ANDROID_GENERICPLAYER_H__
19
20#include <media/stagefright/foundation/AHandler.h>
21#include <media/stagefright/foundation/ALooper.h>
22#include <media/stagefright/foundation/AMessage.h>
23
24//--------------------------------------------------------------------------------------------------
25/**
26 * Message parameters for AHandler messages, see list in GenericPlayer::kWhatxxx
27 */
28#define WHATPARAM_SEEK_SEEKTIME_MS                  "seekTimeMs"
29#define WHATPARAM_LOOP_LOOPING                      "looping"
30#define WHATPARAM_BUFFERING_UPDATE                  "bufferingUpdate"
31#define WHATPARAM_BUFFERING_UPDATETHRESHOLD_PERCENT "buffUpdateThreshold"
32#define WHATPARAM_ATTACHAUXEFFECT                   "attachAuxEffect"
33#define WHATPARAM_SETAUXEFFECTSENDLEVEL             "setAuxEffectSendLevel"
34// Parameters for kWhatSetPlayEvents
35#define WHATPARAM_SETPLAYEVENTS_FLAGS               "setPlayEventsFlags"
36#define WHATPARAM_SETPLAYEVENTS_MARKER              "setPlayEventsMarker"
37#define WHATPARAM_SETPLAYEVENTS_UPDATE              "setPlayEventsUpdate"
38// Parameters for kWhatOneShot (see explanation at definition of kWhatOneShot below)
39#define WHATPARAM_ONESHOT_GENERATION                "oneShotGeneration"
40
41namespace android {
42
43// abstract base class
44class GenericPlayer : public AHandler
45{
46public:
47
48    enum {
49        kEventPrepared                = 0,
50        kEventHasVideoSize            = 1,
51        kEventPrefetchStatusChange    = 2,
52        kEventPrefetchFillLevelUpdate = 3,
53        kEventEndOfStream             = 4,
54        kEventChannelCount            = 5,
55        kEventPlay                    = 6, // SL_PLAYEVENT_*
56        kEventErrorAfterPrepare       = 7, // error after successful prepare
57    };
58
59
60    GenericPlayer(const AudioPlayback_Parameters* params);
61    virtual ~GenericPlayer();
62
63    void init(const notif_cbf_t cbf, void* notifUser);
64    virtual void preDestroy();
65
66    void setDataSource(const char *uri);
67    void setDataSource(int fd, int64_t offset, int64_t length, bool closeAfterUse = false);
68
69    void prepare();
70    virtual void play();
71    void pause();
72    void stop();
73    // timeMsec must be >= 0 or == ANDROID_UNKNOWN_TIME (used by StreamPlayer after discontinuity)
74    void seek(int64_t timeMsec);
75    void loop(bool loop);
76    void setBufferingUpdateThreshold(int16_t thresholdPercent);
77
78    void getDurationMsec(int* msec); //msec != NULL, ANDROID_UNKNOWN_TIME if unknown
79    virtual void getPositionMsec(int* msec) = 0; //msec != NULL, ANDROID_UNKNOWN_TIME if unknown
80
81    virtual void setVideoSurfaceTexture(const sp<IGraphicBufferProducer> &bufferProducer __unused)
82            { }
83
84    void setVolume(float leftVol, float rightVol);
85    void attachAuxEffect(int32_t effectId);
86    void setAuxEffectSendLevel(float level);
87
88    virtual void setPlaybackRate(int32_t ratePermille);
89
90    // Call after changing any of the IPlay settings related to SL_PLAYEVENT_*
91    void setPlayEvents(int32_t eventFlags, int32_t markerPosition, int32_t positionUpdatePeriod);
92
93protected:
94    // mutex used for set vs use of volume, duration, and cache (fill, threshold) settings
95    Mutex mSettingsLock;
96
97    void resetDataLocator();
98    DataLocator2 mDataLocator;
99    int          mDataLocatorType;
100
101    // Constants used to identify the messages in this player's AHandler message loop
102    //   in onMessageReceived()
103    enum {
104        kWhatPrepare         = 0,  // start preparation
105        kWhatNotif           = 1,  // send a notification to client
106        kWhatPlay            = 2,  // start player
107        kWhatPause           = 3,  // pause or stop player
108        kWhatSeek            = 4,  // request a seek to specified position
109        kWhatSeekComplete    = 5,  // seek request has completed
110        kWhatLoop            = 6,  // set the player's looping status
111        kWhatVolumeUpdate    = 7,  // set the channel gains to specified values
112        kWhatBufferingUpdate = 8,
113        kWhatBuffUpdateThres = 9,
114        kWhatAttachAuxEffect = 10,
115        kWhatSetAuxEffectSendLevel = 11,
116        kWhatSetPlayEvents   = 12,  // process new IPlay settings related to SL_PLAYEVENT_*
117        kWhatOneShot         = 13,  // deferred (non-0 timeout) handler for SL_PLAYEVENT_*
118        // As used here, "one-shot" is the software equivalent of a "retriggerable monostable
119        // multivibrator" from electronics.  Briefly, a one-shot is a timer that can be triggered
120        // to fire at some point in the future.  It is "retriggerable" because while the timer
121        // is active, it is possible to replace the current timeout value by a new value.
122        // This is done by cancelling the current timer (using a generation count),
123        // and then posting another timer with the new desired value.
124    };
125
126    // Send a notification to one of the event listeners
127    virtual void notify(const char* event, int data1, bool async);
128    virtual void notify(const char* event, int data1, int data2, bool async);
129
130    // AHandler implementation
131    virtual void onMessageReceived(const sp<AMessage> &msg);
132
133    // Async event handlers (called from GenericPlayer's event loop)
134    virtual void onPrepare();
135    virtual void onNotify(const sp<AMessage> &msg);
136    virtual void onPlay();
137    virtual void onPause();
138    virtual void onSeek(const sp<AMessage> &msg);
139    virtual void onLoop(const sp<AMessage> &msg);
140    virtual void onVolumeUpdate();
141    virtual void onSeekComplete();
142    virtual void onBufferingUpdate(const sp<AMessage> &msg);
143    virtual void onSetBufferingUpdateThreshold(const sp<AMessage> &msg);
144    virtual void onAttachAuxEffect(const sp<AMessage> &msg);
145    virtual void onSetAuxEffectSendLevel(const sp<AMessage> &msg);
146    void onSetPlayEvents(const sp<AMessage> &msg);
147    void onOneShot(const sp<AMessage> &msg);
148
149    // Convenience methods
150    //   for async notifications of prefetch status and cache fill level, needs to be called
151    //     with mSettingsLock locked
152    void notifyStatus();
153    void notifyCacheFill();
154    //   for internal async notification to update state that the player is no longer seeking
155    void seekComplete();
156    void bufferingUpdate(int16_t fillLevelPerMille);
157
158    // Event notification from GenericPlayer to OpenSL ES / OpenMAX AL framework
159    notif_cbf_t mNotifyClient;
160    void*       mNotifyUser;
161    // lock to protect mNotifyClient and mNotifyUser updates
162    Mutex       mNotifyClientLock;
163
164    // Bits for mStateFlags
165    enum {
166        kFlagPrepared               = 1 << 0,   // use only for successful preparation
167        kFlagPreparing              = 1 << 1,
168        kFlagPlaying                = 1 << 2,
169        kFlagBuffering              = 1 << 3,
170        kFlagSeeking                = 1 << 4,   // set if we (not Stagefright) initiated a seek
171        kFlagLooping                = 1 << 5,   // set if looping is enabled
172        kFlagPreparedUnsuccessfully = 1 << 6,
173    };
174
175    // Only accessed from event loop, does not need a mutex
176    uint32_t mStateFlags;
177
178    sp<ALooper> mLooper;
179
180    const AudioPlayback_Parameters mPlaybackParams;
181
182    // protected by mSettingsLock after construction
183    AndroidAudioLevels mAndroidAudioLevels;
184
185    // protected by mSettingsLock
186    int32_t mDurationMsec;
187    int16_t mPlaybackRatePermille;
188
189    CacheStatus_t mCacheStatus;
190    int16_t mCacheFill; // cache fill level + played back level in permille
191    int16_t mLastNotifiedCacheFill; // last cache fill level communicated to the listener
192    int16_t mCacheFillNotifThreshold; // threshold in cache fill level for cache fill to be reported
193
194    // Call any time any of the IPlay copies, current position, or play state changes, and
195    // supply the latest known position or ANDROID_UNKNOWN_TIME if position is unknown to caller.
196    void updateOneShot(int positionMs = ANDROID_UNKNOWN_TIME);
197
198    // players that "render" data to present it to the user (a music player, a video player),
199    // should return true, while players that only decode (hopefully faster than "real time")
200    // should return false.
201    virtual bool advancesPositionInRealTime() const { return true; }
202
203private:
204
205    // Our copy of some important IPlay member variables, except in Android units
206    int32_t mEventFlags;
207    int32_t mMarkerPositionMs;
208    int32_t mPositionUpdatePeriodMs;
209
210    // We need to be able to cancel any pending one-shot event(s) prior to posting
211    // a new one-shot.  As AMessage does not currently support cancellation by
212    // "what" category, we simulate this by keeping a generation counter for
213    // one-shots.  When a one-shot event is delivered, it checks to see if it is
214    // still the current one-shot.  If not, it returns immediately, thus
215    // effectively cancelling itself.  Note that counter wrap-around is possible
216    // but unlikely and benign.
217    int32_t mOneShotGeneration;
218
219    // Play position at time of the most recently delivered SL_PLAYEVENT_HEADATNEWPOS,
220    // or ANDROID_UNKNOWN_TIME if a SL_PLAYEVENT_HEADATNEWPOS has never been delivered.
221    int32_t mDeliveredNewPosMs;
222
223    // Play position most recently observed by updateOneShot, or ANDROID_UNKNOWN_TIME
224    // if the play position has never been observed.
225    int32_t mObservedPositionMs;
226
227    DISALLOW_EVIL_CONSTRUCTORS(GenericPlayer);
228};
229
230} // namespace android
231
232extern void android_player_volumeUpdate(float *pVolumes /*[2]*/, const IVolume *volumeItf,
233        unsigned channelCount, float amplFromDirectLevel, const bool *audibilityFactors /*[2]*/);
234
235#endif /* __ANDROID_GENERICPLAYER_H__ */
236