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