1 /*
2 * Copyright (c) 2010, 2016, Oracle and/or its affiliates. All rights reserved.
3 * DO NOT ALTER OR REMOVE COPYRIGHT NOTICES OR THIS FILE HEADER.
4 *
5 * This code is free software; you can redistribute it and/or modify it
6 * under the terms of the GNU General Public License version 2 only, as
7 * published by the Free Software Foundation. Oracle designates this
8 * particular file as subject to the "Classpath" exception as provided
9 * by Oracle in the LICENSE file that accompanied this code.
10 *
11 * This code is distributed in the hope that it will be useful, but WITHOUT
12 * ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or
13 * FITNESS FOR A PARTICULAR PURPOSE. See the GNU General Public License
14 * version 2 for more details (a copy is included in the LICENSE file that
15 * accompanied this code).
16 *
17 * You should have received a copy of the GNU General Public License version
18 * 2 along with this work; if not, write to the Free Software Foundation,
19 * Inc., 51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA.
20 *
21 * Please contact Oracle, 500 Oracle Parkway, Redwood Shores, CA 94065 USA
22 * or visit www.oracle.com if you need additional information or have any
23 * questions.
24 */
25
26 package com.sun.media.jfxmedia;
27
28 import com.sun.media.jfxmedia.effects.AudioEqualizer;
29 import com.sun.media.jfxmedia.events.PlayerStateListener;
30 import com.sun.media.jfxmedia.events.VideoTrackSizeListener;
31 import com.sun.media.jfxmedia.control.VideoRenderControl;
32 import com.sun.media.jfxmedia.control.MediaPlayerOverlay;
33 import com.sun.media.jfxmedia.effects.AudioSpectrum;
34 import com.sun.media.jfxmedia.events.AudioSpectrumListener;
35 import com.sun.media.jfxmedia.events.MarkerListener;
36 import com.sun.media.jfxmedia.events.MediaErrorListener;
37 import com.sun.media.jfxmedia.events.BufferListener;
38 import com.sun.media.jfxmedia.events.PlayerStateEvent.PlayerState;
39 import com.sun.media.jfxmedia.events.PlayerTimeListener;
40
41 /**
42 * MediaPlayer class provides control of media playback. Get a MediaPlayer from
43 * either MediaManager or MediaRecorder.
44 *
45 * @see MediaManager
46 * @see MediaRecorder
47 */
48 public interface MediaPlayer {
49 //**************************************************************************
50 //***** Public control functions
51 //**************************************************************************
52
53 /**
54 * Adds a listener for warnings which occur within the lifespan of the player.
55 *
56 * @param listener The warning listener.
57 * @throws IllegalArgumentException if <code>listener</code> is
58 * <code>null</code>.
59 */
60 public void addMediaErrorListener(MediaErrorListener listener);
61
62 /**
63 * Removes a listener for warnings.
64 *
65 * @param listener The warning listener.
66 * @throws IllegalArgumentException if <code>listener</code> is
67 * <code>null</code>.
68 */
69 public void removeMediaErrorListener(MediaErrorListener listener);
70
71 /**
72 * Adds a listener for media state.
73 *
74 * @param listener
75 * @throws IllegalArgumentException if <code>listener</code> is
76 * <code>null</code>.
77 */
78 public void addMediaPlayerListener(PlayerStateListener listener);
79
80 /**
81 * Removes a listener for media state.
82 *
83 * @param listener
84 * @throws IllegalArgumentException if <code>listener</code> is
85 * <code>null</code>.
86 */
87 public void removeMediaPlayerListener(PlayerStateListener listener);
88
89 /**
90 * Adds a listener for player time events.
91 *
92 * @param listener
93 */
94 public void addMediaTimeListener(PlayerTimeListener listener);
95
96 /**
97 * Removes a listener for player time events.
98 *
99 * @param listener
100 */
101 public void removeMediaTimeListener(PlayerTimeListener listener);
102
103 /**
104 * Adds a listener for video track frame dimensions.
105 *
106 * @param listener
107 * @throws IllegalArgumentException if <code>listener</code> is
108 * <code>null</code>.
109 */
110 public void addVideoTrackSizeListener(VideoTrackSizeListener listener);
111
112 /**
113 * Removes a listener for video track frame dimensions.
114 *
115 * @param listener
116 * @throws IllegalArgumentException if <code>listener</code> is
117 * <code>null</code>.
118 */
119 public void removeVideoTrackSizeListener(VideoTrackSizeListener listener);
120
121 /**
122 * Adds a listener for marker events.
123 *
124 * @param listener
125 * @throws IllegalArgumentException if <code>listener</code> is
126 * <code>null</code>.
127 */
128 public void addMarkerListener(MarkerListener listener);
129
130 /**
131 * Removes a listener for marker events.
132 *
133 * @param listener
134 * @throws IllegalArgumentException if <code>listener</code> is
135 * <code>null</code>.
136 */
137 public void removeMarkerListener(MarkerListener listener);
138
139 /**
140 * Adds a listener for all buffer events.
141 *
142 * @param listener
143 * @throws IllegalArgumentException if <code>listener</code> is
144 * <code>null</code>.
145 */
146 public void addBufferListener(BufferListener listener);
147
148 /**
149 * Removes a listener for buffer events.
150 *
151 * @param listener
152 * @throws IllegalArgumentException if <code>listener</code> is
153 * <code>null</code>.
154 */
155 public void removeBufferListener(BufferListener listener);
156
157 /**
158 * Adds a listener for audio spectrum events.
159 *
160 * @param listener
161 * @throws IllegalArgumentException if <code>listener</code> is
162 * <code>null</code>.
163 */
164 public void addAudioSpectrumListener(AudioSpectrumListener listener);
165
166 /**
167 * Removes a listener for audio spectrum events.
168 *
169 * @param listener
170 * @throws IllegalArgumentException if <code>listener</code> is
171 * <code>null</code>.
172 */
173 public void removeAudioSpectrumListener(AudioSpectrumListener listener);
174
175 /**
176 * Returns the video rendering support interface.
177 *
178 * @return A <code>VideoRenderControl</code> instance.
179 */
180 public VideoRenderControl getVideoRenderControl();
181
182 /**
183 * Returns the media player overlay support interface.
184 *
185 * @return A <code>MediaPlayerOverlay</code> instance.
186 */
187 public MediaPlayerOverlay getMediaPlayerOverlay();
188
189 /**
190 * Gets a Media object.
191 *
192 * @return Media object.
193 */
194 public Media getMedia();
195
196 /**
197 * Set the amount of time to delay the audio. A positive value makes audio
198 * render later, and a negative value makes audio render earlier.
199 *
200 * @param delay time in milliseconds
201 */
202 public void setAudioSyncDelay(long delay);
203
204 /**
205 * Retrieve the audio rendering delay.
206 */
207 public long getAudioSyncDelay();
208
209 /**
210 * Begins playing of the media. To ensure smooth playback, catch the
211 * onReady event in the MediaPlayerListener before playing.
212 */
213 public void play();
214
215 /**
216 * Stops playing of the media and resets the play time to 0.
217 */
218 public void stop();
219
220 /**
221 * Pauses the media playing. Calling play() after pause() will continue
222 * playing the media from where it left off.
223 */
224 public void pause();
225
226 /**
227 * Get the rate of playback.
228 */
229 public float getRate();
230
231 //**************************************************************************
232 //***** Public properties
233 //**************************************************************************
234 /**
235 * Sets the rate of playback. A positive value indicates forward play and
236 * a negative value reverse play.
237 *
238 * @param rate
239 */
240 public void setRate(float rate);
241
242 /**
243 * Gets the current presentation time. If the time is unknown or cannot be
244 * obtained when this method is invoked, a negative value will be returned.
245 *
246 * @return the current presentation time
247 */
248 public double getPresentationTime();
249
250 /**
251 * Gets the current volume.
252 *
253 * @return the current volume
254 */
255 public float getVolume();
256
257 /**
258 * Sets the volume. Values will be clamped to the range
259 * <code>[0, 1.0]</code>.
260 *
261 * @param volume A value in the range <code>[0, 1.0]</code>.
262 */
263 public void setVolume(float volume);
264
265 /**
266 * Gets the muted state. While muted no audio will be heard.
267 * @return true if audio is muted.
268 */
269 public boolean getMute();
270
271 /**
272 * Enables/disable mute. If mute is enabled then disabled, the previous
273 * volume goes into effect.
274 */
275 public void setMute(boolean enable);
276
277 /**
278 * Gets the current balance.
279 *
280 * @return the current balance
281 */
282 public float getBalance();
283
284 /**
285 * Sets the balance. A negative value indicates left of center and a positive
286 * value right of center. Values will be clamped to the range
287 * <code>[-1.0, 1.0]</code>.
288 *
289 * @param balance A value in the range <code>[-1.0, 1.0]</code>.
290 */
291 public void setBalance(float balance);
292
293 /**
294 * Gets the master audio equalizer for the player.
295 *
296 * @return AudioEqualizer object
297 */
298 public AudioEqualizer getEqualizer();
299
300 /**
301 * Gets the audio spectrum controller for the player.
302 *
303 * @return AudioSpectrum object
304 */
305 public AudioSpectrum getAudioSpectrum();
306
307 /**
308 * Gets the duration in seconds. If the duration is unknown or cannot be
309 * obtained when this method is invoked, a negative value will be returned.
310 */
311 public double getDuration();
312
313 /**
314 * Gets the time within the duration of the media to start playing.
315 */
316 public double getStartTime();
317
318 /**
319 * Sets the start time within the media to play.
320 */
321 public void setStartTime(double streamTime);
322
323 /**
324 * Gets the time within the duration of the media to stop playing.
325 */
326 public double getStopTime();
327
328 /**
329 * Sets the stop time within the media to stop playback.
330 */
331 public void setStopTime(double streamTime);
332
333 /**
334 * Seeks playback to the specified time. The state of the player
335 * is unchanged. A negative value will be clamped to zero, and a positive
336 * value to the duration, if known.
337 *
338 * @param streamTime The time in seconds to which to seek.
339 */
340 public void seek(double streamTime);
341
342 /**
343 * Retrieves the current {@link PlayerState state} of the player.
344 * @return the current player state.
345 */
346 public PlayerState getState();
347 /**
348 * Release any resources held by this player. The player will be unusable
349 * after this method is invoked.
350 */
351 public void dispose();
352 }