git.sesse.net Git - vlc/blob - 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:(NSUInteger)value;
 114 - (NSUInteger)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) NSUInteger 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:(NSInteger)value;
 223 - (NSInteger)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