1 /*
2  * Copyright 2017 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_MEDIAPLAYER2INTERFACE_H
18 #define ANDROID_MEDIAPLAYER2INTERFACE_H
19 
20 #ifdef __cplusplus
21 
22 #include <sys/types.h>
23 #include <utils/Errors.h>
24 #include <utils/String8.h>
25 #include <utils/RefBase.h>
26 
27 #include <media/AVSyncSettings.h>
28 #include <media/AudioResamplerPublic.h>
29 #include <media/AudioSystem.h>
30 #include <media/AudioTimestamp.h>
31 #include <media/BufferingSettings.h>
32 #include <media/Metadata.h>
33 #include <media/stagefright/foundation/AHandler.h>
34 #include <mediaplayer2/MediaPlayer2Types.h>
35 
36 // Fwd decl to make sure everyone agrees that the scope of struct sockaddr_in is
37 // global, and not in android::
38 struct sockaddr_in;
39 
40 namespace android {
41 
42 struct DataSourceDesc;
43 class Parcel;
44 struct ANativeWindowWrapper;
45 
46 #define DEFAULT_AUDIOSINK_BUFFERCOUNT 4
47 #define DEFAULT_AUDIOSINK_BUFFERSIZE 1200
48 #define DEFAULT_AUDIOSINK_SAMPLERATE 44100
49 
50 // when the channel mask isn't known, use the channel count to derive a mask in AudioSink::open()
51 #define CHANNEL_MASK_USE_CHANNEL_ORDER 0
52 
53 // duration below which we do not allow deep audio buffering
54 #define AUDIO_SINK_MIN_DEEP_BUFFER_DURATION_US 5000000
55 
56 class MediaPlayer2InterfaceListener: public RefBase
57 {
58 public:
59     virtual void notify(int64_t srcId, int msg, int ext1, int ext2, const Parcel *obj) = 0;
60 };
61 
62 class MediaPlayer2Interface : public AHandler {
63 public:
64     // AudioSink: abstraction layer for audio output
65     class AudioSink : public RefBase {
66     public:
67         enum cb_event_t {
68             CB_EVENT_FILL_BUFFER,   // Request to write more data to buffer.
69             CB_EVENT_STREAM_END,    // Sent after all the buffers queued in AF and HW are played
70                                     // back (after stop is called)
71             CB_EVENT_TEAR_DOWN      // The AudioTrack was invalidated due to use case change:
72                                     // Need to re-evaluate offloading options
73         };
74 
75         // Callback returns the number of bytes actually written to the buffer.
76         typedef size_t (*AudioCallback)(
77                 AudioSink *audioSink, void *buffer, size_t size, void *cookie, cb_event_t event);
78 
~AudioSink()79         virtual ~AudioSink() {}
80         virtual bool ready() const = 0; // audio output is open and ready
81         virtual ssize_t bufferSize() const = 0;
82         virtual ssize_t frameCount() const = 0;
83         virtual ssize_t channelCount() const = 0;
84         virtual ssize_t frameSize() const = 0;
85         virtual uint32_t latency() const = 0;
86         virtual float msecsPerFrame() const = 0;
87         virtual status_t getPosition(uint32_t *position) const = 0;
88         virtual status_t getTimestamp(AudioTimestamp &ts) const = 0;
89         virtual int64_t getPlayedOutDurationUs(int64_t nowUs) const = 0;
90         virtual status_t getFramesWritten(uint32_t *frameswritten) const = 0;
91         virtual audio_session_t getSessionId() const = 0;
92         virtual audio_stream_type_t getAudioStreamType() const = 0;
93         virtual uint32_t getSampleRate() const = 0;
94         virtual int64_t getBufferDurationInUs() const = 0;
95 
96         // If no callback is specified, use the "write" API below to submit
97         // audio data.
98         virtual status_t open(
99                 uint32_t sampleRate, int channelCount, audio_channel_mask_t channelMask,
100                 audio_format_t format=AUDIO_FORMAT_PCM_16_BIT,
101                 int bufferCount=DEFAULT_AUDIOSINK_BUFFERCOUNT,
102                 AudioCallback cb = NULL,
103                 void *cookie = NULL,
104                 audio_output_flags_t flags = AUDIO_OUTPUT_FLAG_NONE,
105                 const audio_offload_info_t *offloadInfo = NULL,
106                 bool doNotReconnect = false,
107                 uint32_t suggestedFrameCount = 0) = 0;
108 
109         virtual status_t start() = 0;
110 
111         /* Input parameter |size| is in byte units stored in |buffer|.
112          * Data is copied over and actual number of bytes written (>= 0)
113          * is returned, or no data is copied and a negative status code
114          * is returned (even when |blocking| is true).
115          * When |blocking| is false, AudioSink will immediately return after
116          * part of or full |buffer| is copied over.
117          * When |blocking| is true, AudioSink will wait to copy the entire
118          * buffer, unless an error occurs or the copy operation is
119          * prematurely stopped.
120          */
121         virtual ssize_t write(const void* buffer, size_t size, bool blocking = true) = 0;
122 
123         virtual void stop() = 0;
124         virtual void flush() = 0;
125         virtual void pause() = 0;
126         virtual void close() = 0;
127 
128         virtual status_t setPlaybackRate(const AudioPlaybackRate& rate) = 0;
129         virtual status_t getPlaybackRate(AudioPlaybackRate* rate /* nonnull */) = 0;
needsTrailingPadding()130         virtual bool needsTrailingPadding() {
131             return true;
132         }
133 
setParameters(const String8 &)134         virtual status_t setParameters(const String8& /* keyValuePairs */) {
135             return NO_ERROR;
136         }
getParameters(const String8 &)137         virtual String8 getParameters(const String8& /* keys */) {
138             return String8::empty();
139         }
140 
141         // AudioRouting
142         virtual status_t    setOutputDevice(audio_port_handle_t deviceId);
143         virtual status_t    getRoutedDeviceId(audio_port_handle_t* deviceId);
144         virtual status_t    enableAudioDeviceCallback(bool enabled);
145     };
146 
MediaPlayer2Interface()147     MediaPlayer2Interface() : mListener(NULL) { }
~MediaPlayer2Interface()148     virtual ~MediaPlayer2Interface() { }
149     virtual status_t initCheck() = 0;
150 
setAudioSink(const sp<AudioSink> & audioSink)151     virtual void setAudioSink(const sp<AudioSink>& audioSink) {
152         mAudioSink = audioSink;
153     }
154 
155     virtual status_t setDataSource(const sp<DataSourceDesc> &dsd) = 0;
156 
157     virtual status_t prepareNextDataSource(const sp<DataSourceDesc> &dsd) = 0;
158 
159     virtual status_t playNextDataSource(int64_t srcId) = 0;
160 
161     // pass the buffered native window to the media player service
162     virtual status_t setVideoSurfaceTexture(const sp<ANativeWindowWrapper>& nww) = 0;
163 
getBufferingSettings(BufferingSettings * buffering)164     virtual status_t getBufferingSettings(BufferingSettings* buffering /* nonnull */) {
165         *buffering = BufferingSettings();
166         return OK;
167     }
setBufferingSettings(const BufferingSettings &)168     virtual status_t setBufferingSettings(const BufferingSettings& /* buffering */) {
169         return OK;
170     }
171 
172     virtual status_t prepareAsync() = 0;
173     virtual status_t start() = 0;
174     virtual status_t stop() = 0;
175     virtual status_t pause() = 0;
176     virtual bool isPlaying() = 0;
setPlaybackSettings(const AudioPlaybackRate & rate)177     virtual status_t setPlaybackSettings(const AudioPlaybackRate& rate) {
178         // by default, players only support setting rate to the default
179         if (!isAudioPlaybackRateEqual(rate, AUDIO_PLAYBACK_RATE_DEFAULT)) {
180             return BAD_VALUE;
181         }
182         return OK;
183     }
getPlaybackSettings(AudioPlaybackRate * rate)184     virtual status_t getPlaybackSettings(AudioPlaybackRate* rate /* nonnull */) {
185         *rate = AUDIO_PLAYBACK_RATE_DEFAULT;
186         return OK;
187     }
setSyncSettings(const AVSyncSettings & sync,float)188     virtual status_t setSyncSettings(const AVSyncSettings& sync, float /* videoFps */) {
189         // By default, players only support setting sync source to default; all other sync
190         // settings are ignored. There is no requirement for getters to return set values.
191         if (sync.mSource != AVSYNC_SOURCE_DEFAULT) {
192             return BAD_VALUE;
193         }
194         return OK;
195     }
getSyncSettings(AVSyncSettings * sync,float * videoFps)196     virtual status_t getSyncSettings(
197             AVSyncSettings* sync /* nonnull */, float* videoFps /* nonnull */) {
198         *sync = AVSyncSettings();
199         *videoFps = -1.f;
200         return OK;
201     }
202     virtual status_t seekTo(
203             int64_t msec, MediaPlayer2SeekMode mode = MediaPlayer2SeekMode::SEEK_PREVIOUS_SYNC) = 0;
204     virtual status_t getCurrentPosition(int64_t *msec) = 0;
205     virtual status_t getDuration(int64_t *msec) = 0;
206     virtual status_t reset() = 0;
notifyAt(int64_t)207     virtual status_t notifyAt(int64_t /* mediaTimeUs */) {
208         return INVALID_OPERATION;
209     }
210     virtual status_t setLooping(int loop) = 0;
211     virtual status_t setParameter(int key, const Parcel &request) = 0;
212     virtual status_t getParameter(int key, Parcel *reply) = 0;
213 
214     // Invoke a generic method on the player by using opaque parcels
215     // for the request and reply.
216     //
217     // @param request Parcel that is positioned at the start of the
218     //                data sent by the java layer.
219     // @param[out] reply Parcel to hold the reply data. Cannot be null.
220     // @return OK if the call was successful.
221     virtual status_t invoke(const Parcel& request, Parcel *reply) = 0;
222 
223     // The Client in the MetadataPlayerService calls this method on
224     // the native player to retrieve all or a subset of metadata.
225     //
226     // @param ids SortedList of metadata ID to be fetch. If empty, all
227     //            the known metadata should be returned.
228     // @param[inout] records Parcel where the player appends its metadata.
229     // @return OK if the call was successful.
getMetadata(const media::Metadata::Filter &,Parcel *)230     virtual status_t getMetadata(const media::Metadata::Filter& /* ids */,
231                                  Parcel* /* records */) {
232         return INVALID_OPERATION;
233     };
234 
setListener(const sp<MediaPlayer2InterfaceListener> & listener)235     void setListener(const sp<MediaPlayer2InterfaceListener> &listener) {
236         Mutex::Autolock autoLock(mListenerLock);
237         mListener = listener;
238     }
239 
240     void sendEvent(int64_t srcId, int msg, int ext1=0, int ext2=0, const Parcel *obj=NULL) {
241         sp<MediaPlayer2InterfaceListener> listener;
242         {
243             Mutex::Autolock autoLock(mListenerLock);
244             listener = mListener;
245         }
246 
247         if (listener) {
248             listener->notify(srcId, msg, ext1, ext2, obj);
249         }
250     }
251 
dump(int,const Vector<String16> &)252     virtual status_t dump(int /* fd */, const Vector<String16>& /* args */) const {
253         return INVALID_OPERATION;
254     }
255 
onMessageReceived(const sp<AMessage> &)256     virtual void onMessageReceived(const sp<AMessage> & /* msg */) override { }
257 
258     // Modular DRM
prepareDrm(const uint8_t[16],const Vector<uint8_t> &)259     virtual status_t prepareDrm(const uint8_t /* uuid */[16],
260                                 const Vector<uint8_t>& /* drmSessionId */) {
261         return INVALID_OPERATION;
262     }
releaseDrm()263     virtual status_t releaseDrm() {
264         return INVALID_OPERATION;
265     }
266 
267 protected:
268     sp<AudioSink> mAudioSink;
269 
270 private:
271     Mutex mListenerLock;
272     sp<MediaPlayer2InterfaceListener> mListener;
273 };
274 
275 }; // namespace android
276 
277 #endif // __cplusplus
278 
279 
280 #endif // ANDROID_MEDIAPLAYER2INTERFACE_H
281