macosx/framework: Make sure remainingTime is KVO.
[vlc.git] / projects / macosx / framework / Headers / Public / VLCMediaPlayer.h
1 /*****************************************************************************
2  * VLCMediaPlayer.h: VLCKit.framework VLCMediaPlayer header
3  *****************************************************************************
4  * Copyright (C) 2007-2009 Pierre d'Herbemont
5  * Copyright (C) 2007-2009 the VideoLAN team
6  * Partial Copyright (C) 2009 Felix Paul Kühne
7  * $Id$
8  *
9  * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
10  *          Felix Paul Kühne <fkuehne # videolan.org>
11  *
12  * This program is free software; you can redistribute it and/or modify
13  * it under the terms of the GNU General Public License as published by
14  * the Free Software Foundation; either version 2 of the License, or
15  * (at your option) any later version.
16  *
17  * This program is distributed in the hope that it will be useful,
18  * but WITHOUT ANY WARRANTY; without even the implied warranty of
19  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
20  * GNU General Public License for more details.
21  *
22  * You should have received a copy of the GNU General Public License
23  * along with this program; if not, write to the Free Software
24  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
25  *****************************************************************************/
26
27 #import "VLCMedia.h"
28 #import "VLCVideoView.h"
29 #import "VLCVideoLayer.h"
30 #import "VLCTime.h"
31 #import "VLCAudio.h"
32
33 /* Notification Messages */
34 extern NSString * VLCMediaPlayerTimeChanged;
35 extern NSString * VLCMediaPlayerStateChanged;
36
37 /**
38  * VLCMediaPlayerState describes the state of the media player.
39  */
40 typedef enum VLCMediaPlayerState
41 {
42     VLCMediaPlayerStateStopped,        //< Player has stopped
43     VLCMediaPlayerStateOpening,        //< Stream is opening
44     VLCMediaPlayerStateBuffering,      //< Stream is buffering
45     VLCMediaPlayerStateEnded,          //< Stream has ended
46     VLCMediaPlayerStateError,          //< Player has generated an error
47     VLCMediaPlayerStatePlaying,        //< Stream is playing
48     VLCMediaPlayerStatePaused          //< Stream is paused
49 } VLCMediaPlayerState;
50
51 /**
52  * Returns the name of the player state as a string.
53  * \param state The player state.
54  * \return A string containing the name of state. If state is not a valid state, returns nil.
55  */
56 extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
57
58 /**
59  * Formal protocol declaration for playback delegates.  Allows playback messages
60  * to be trapped by delegated objects.
61  */
62 @protocol VLCMediaPlayerDelegate
63 /**
64  * Sent by the default notification center whenever the player's time has changed.
65  * \details Discussion The value of aNotification is always an VLCMediaPlayerTimeChanged notification. You can retrieve 
66  * the VLCMediaPlayer object in question by sending object to aNotification.
67  */
68 - (void)mediaPlayerTimeChanged:(NSNotification *)aNotification;
69
70 /**
71  * Sent by the default notification center whenever the player's state has changed.
72  * \details Discussion The value of aNotification is always an VLCMediaPlayerStateChanged notification. You can retrieve 
73  * the VLCMediaPlayer object in question by sending object to aNotification.
74  */
75 - (void)mediaPlayerStateChanged:(NSNotification *)aNotification;
76 @end
77
78 // TODO: Should we use medialist_player or our own flavor of media player?
79 @interface VLCMediaPlayer : NSObject 
80 {
81     id delegate;                        //< Object delegate
82     void * instance;                    //  Internal
83     VLCMedia * media;                   //< Current media being played
84     VLCTime * cachedTime;               //< Cached time of the media being played
85     VLCTime * cachedRemainingTime;      //< Cached remaining time of the media being played
86     VLCMediaPlayerState cachedState;    //< Cached state of the media being played
87     float position;                     //< The position of the media being played
88     id drawable;                        //< The drawable associated to this media player
89 }
90
91 /* Initializers */
92 - (id)initWithVideoView:(VLCVideoView *)aVideoView;
93 - (id)initWithVideoLayer:(VLCVideoLayer *)aVideoLayer;
94
95 /* Properties */
96 - (void)setDelegate:(id)value;
97 - (id)delegate;
98
99 /* Video View Options */
100 // TODO: Should be it's own object?
101
102 - (void)setVideoView:(VLCVideoView *)aVideoView;
103 - (void)setVideoLayer:(VLCVideoLayer *)aVideoLayer;
104
105 @property (retain) id drawable; /* The videoView or videoLayer */
106
107 - (void)setVideoAspectRatio:(char *)value;
108 - (char *)videoAspectRatio;
109
110 - (void)setVideoCropGeometry:(char *)value;
111 - (char *)videoCropGeometry;
112
113 - (void)setVideoTeleText:(int)value;
114 - (int)videoTeleText;
115
116 /**
117  * Take a snapshot of the current video.
118  *
119  * If width AND height is 0, original size is used.
120  * If width OR height is 0, original aspect-ratio is preserved.
121  *
122  * \param path the path where to save the screenshot to
123  * \param width the snapshot's width
124  * \param height the snapshot's height
125  */
126 - (void)saveVideoSnapshotAt: (NSString *)path withWidth:(NSUInteger)width andHeight:(NSUInteger)height;
127
128 /**
129  * Enable or disable deinterlace filter
130  *
131  * \param name of deinterlace filter to use (availability depends on underlying VLC version)
132  * \param enable boolean to enable or disable deinterlace filter
133  */
134 - (void)setDeinterlaceFilter: (NSString *)name enabled: (BOOL)enabled;
135
136 @property float rate;
137
138 @property (readonly) VLCAudio * audio;
139
140 /* Video Information */
141 - (NSSize)videoSize;
142 - (BOOL)hasVideoOut;
143 - (float)framesPerSecond;
144
145 /**
146  * Sets the current position (or time) of the feed.
147  * \param value New time to set the current position to.  If time is [VLCTime nullTime], 0 is assumed.
148  */
149 - (void)setTime:(VLCTime *)value;
150
151 /** 
152  * Returns the current position (or time) of the feed.
153  * \return VLCTIme object with current time.
154  */
155 - (VLCTime *)time;
156
157 @property (readonly) VLCTime *remainingTime;
158 @property (readonly) int fps;
159
160 /**
161  * Return the current video subtitle index
162  * \return 0 if none is set.
163  *
164  * Pass 0 to disable.
165  */
166 @property (readwrite) NSUInteger currentVideoSubTitleIndex;
167
168 /**
169  * Return the video subtitle tracks
170  *
171  * It includes the disabled fake track at index 0.
172  */
173 - (NSArray *)videoSubTitles;
174
175 /**
176  * Load and set a specific video subtitle, from a file.
177  * \param path to a file
178  * \return if the call succeed..
179  */
180 - (BOOL)openVideoSubTitlesFromFile:(NSString *)path;
181
182 /**
183  * Chapter selection and enumeration, it is bound
184  * to a title option.
185  */
186
187 /**
188  * Return the current video subtitle index, or
189  * \return NSNotFound if none is set.
190  *
191  * To disable subtitle pass NSNotFound.
192  */
193 @property (readwrite) NSUInteger currentChapterIndex;
194 - (void)previousChapter;
195 - (void)nextChapter;
196 - (NSArray *)chaptersForTitleIndex:(NSUInteger)titleIndex;
197
198 /**
199  * Title selection and enumeration
200  * \return NSNotFound if none is set.
201  */
202 @property (readwrite) NSUInteger currentTitleIndex;
203 - (NSArray *)titles;
204
205 /* Audio Options */
206
207 /**
208  * Return the current audio track index
209  * \return 0 if none is set.
210  *
211  * Pass 0 to disable.
212  */
213 @property (readwrite) NSUInteger currentAudioTrackIndex;
214
215 /**
216  * Return the audio tracks
217  *
218  * It includes the "Disable" fake track at index 0.
219  */
220 - (NSArray *)audioTracks;
221
222 - (void)setAudioChannel:(int)value;
223 - (int)audioChannel;
224
225 /* Media Options */
226 - (void)setMedia:(VLCMedia *)value;
227 - (VLCMedia *)media;
228
229 /* Playback Operations */
230 /**
231  * Plays a media resource using the currently selected media controller (or 
232  * default controller.  If feed was paused then the feed resumes at the position 
233  * it was paused in.
234  * \return A Boolean determining whether the stream was played or not.
235  */
236 - (BOOL)play;
237
238 /**
239  * Toggle's the pause state of the feed.
240  */
241 - (void)pause;
242
243 /**
244  * Stop the playing.
245  */
246 - (void)stop;
247
248 /**
249  * Fast forwards through the feed at the standard 1x rate.
250  */
251 - (void)fastForward;
252
253 /**
254  * Fast forwards through the feed at the rate specified.
255  * \param rate Rate at which the feed should be fast forwarded.
256  */
257 - (void)fastForwardAtRate:(float)rate;
258
259 /**
260  * Rewinds through the feed at the standard 1x rate.
261  */
262 - (void)rewind;
263
264 /**
265  * Rewinds through the feed at the rate specified.
266  * \param rate Rate at which the feed should be fast rewound.
267  */
268 - (void)rewindAtRate:(float)rate;
269
270 /**
271  * Jumps shortly backward in current stream if seeking is supported.
272  * \param interval to skip, in sec.
273  */
274 - (void)jumpBackward:(NSInteger)interval;
275
276 /**
277  * Jumps shortly forward in current stream if seeking is supported.
278  * \param interval to skip, in sec.
279  */
280 - (void)jumpForward:(NSInteger)interval;
281
282 /**
283  * Jumps shortly backward in current stream if seeking is supported.
284  */
285 - (void)extraShortJumpBackward;
286
287 /**
288  * Jumps shortly forward in current stream if seeking is supported.
289  */
290 - (void)extraShortJumpForward;
291
292 /**
293  * Jumps shortly backward in current stream if seeking is supported.
294  */
295 - (void)shortJumpBackward;
296
297 /**
298  * Jumps shortly forward in current stream if seeking is supported.
299  */
300 - (void)shortJumpForward;
301
302 /**
303  * Jumps shortly backward in current stream if seeking is supported.
304  */
305 - (void)mediumJumpBackward;
306
307 /**
308  * Jumps shortly forward in current stream if seeking is supported.
309  */
310 - (void)mediumJumpForward;
311
312 /**
313  * Jumps shortly backward in current stream if seeking is supported.
314  */
315 - (void)longJumpBackward;
316
317 /**
318  * Jumps shortly forward in current stream if seeking is supported.
319  */
320 - (void)longJumpForward;
321
322 /* Playback Information */
323 /**
324  * Playback state flag identifying that the stream is currently playing.
325  * \return TRUE if the feed is playing, FALSE if otherwise.
326  */
327 - (BOOL)isPlaying;
328
329 /**
330  * Playback state flag identifying wheather the stream will play.
331  * \return TRUE if the feed is ready for playback, FALSE if otherwise.
332  */
333 - (BOOL)willPlay;
334
335 /**
336  * Playback's current state.
337  * \see VLCMediaState
338  */
339 - (VLCMediaPlayerState)state;
340
341 /**
342  * Returns the receiver's position in the reading. 
343  * \return A number between 0 and 1. indicating the position
344  */
345 - (float)position;
346 - (void)setPosition:(float)newPosition;
347
348 - (BOOL)isSeekable;
349
350 - (BOOL)canPause;
351
352 @end