VLCMedia.h 17.7 KB
Newer Older
1
/*****************************************************************************
2
 * VLCMedia.h: VLCKit.framework VLCMedia header
3 4
 *****************************************************************************
 * Copyright (C) 2007 Pierre d'Herbemont
5
 * Copyright (C) 2013 Felix Paul Kühne
6
 * Copyright (C) 2007-2013 VLC authors and VideoLAN
7 8 9
 * $Id$
 *
 * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
10
 *          Felix Paul Kühne <fkuehne # videolan.org>
11
 *
12 13 14
 * This program is free software; you can redistribute it and/or modify it
 * under the terms of the GNU Lesser General Public License as published by
 * the Free Software Foundation; either version 2.1 of the License, or
15 16 17 18
 * (at your option) any later version.
 *
 * This program is distributed in the hope that it will be useful,
 * but WITHOUT ANY WARRANTY; without even the implied warranty of
19 20
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
21
 *
22 23 24
 * You should have received a copy of the GNU Lesser General Public License
 * along with this program; if not, write to the Free Software Foundation,
 * Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
25 26
 *****************************************************************************/

Pierre's avatar
Pierre committed
27
#import <Foundation/Foundation.h>
28 29 30 31 32 33 34
#import "VLCMediaList.h"
#import "VLCTime.h"

/* Meta Dictionary Keys */
/**
 * Standard dictionary keys for retreiving meta data.
 */
35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52
extern NSString *const VLCMetaInformationTitle;          /* NSString */
extern NSString *const VLCMetaInformationArtist;         /* NSString */
extern NSString *const VLCMetaInformationGenre;          /* NSString */
extern NSString *const VLCMetaInformationCopyright;      /* NSString */
extern NSString *const VLCMetaInformationAlbum;          /* NSString */
extern NSString *const VLCMetaInformationTrackNumber;    /* NSString */
extern NSString *const VLCMetaInformationDescription;    /* NSString */
extern NSString *const VLCMetaInformationRating;         /* NSString */
extern NSString *const VLCMetaInformationDate;           /* NSString */
extern NSString *const VLCMetaInformationSetting;        /* NSString */
extern NSString *const VLCMetaInformationURL;            /* NSString */
extern NSString *const VLCMetaInformationLanguage;       /* NSString */
extern NSString *const VLCMetaInformationNowPlaying;     /* NSString */
extern NSString *const VLCMetaInformationPublisher;      /* NSString */
extern NSString *const VLCMetaInformationEncodedBy;      /* NSString */
extern NSString *const VLCMetaInformationArtworkURL;     /* NSString */
extern NSString *const VLCMetaInformationArtwork;        /* NSImage  */
extern NSString *const VLCMetaInformationTrackID;        /* NSString */
53 54 55 56 57 58 59 60
extern NSString *const VLCMetaInformationTrackTotal;     /* NSString */
extern NSString *const VLCMetaInformationDirector;       /* NSString */
extern NSString *const VLCMetaInformationSeason;         /* NSString */
extern NSString *const VLCMetaInformationEpisode;        /* NSString */
extern NSString *const VLCMetaInformationShowName;       /* NSString */
extern NSString *const VLCMetaInformationActors;         /* NSString */
extern NSString *const VLCMetaInformationAlbumArtist;    /* NSString */
extern NSString *const VLCMetaInformationDiscNumber;     /* NSString */
61 62 63 64 65

/* Notification Messages */
/**
 * Available notification messages.
 */
66
extern NSString *const VLCMediaMetaChanged;  //< Notification message for when the media's meta data has changed
67 68 69 70 71

// Forward declarations, supresses compiler error messages
@class VLCMediaList;
@class VLCMedia;

James Dumay's avatar
James Dumay committed
72
typedef NS_ENUM(NSInteger, VLCMediaState) {
73 74 75
    VLCMediaStateNothingSpecial,        //< Nothing
    VLCMediaStateBuffering,             //< Stream is buffering
    VLCMediaStatePlaying,               //< Stream is playing
Konstantin Pavlov's avatar
Konstantin Pavlov committed
76
    VLCMediaStateError,                 //< Can't be played because an error occurred
77
};
78

79 80 81 82
/**
 * Informal protocol declaration for VLCMedia delegates.  Allows data changes to be
 * trapped.
 */
83
@protocol VLCMediaDelegate <NSObject>
84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100
// TODO: SubItemAdded/SubItemRemoved implementation.  Not sure if we really want to implement this.
///**
// * Delegate method called whenever a sub item has been added to the specified VLCMedia.
// * \param aMedia The media resource that has received the new sub item.
// * \param childMedia The new sub item added.
// * \param index Location of the new subitem in the aMedia's sublist.
// */
// - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;

///**
// * Delegate method called whenever a sub item has been removed from the specified VLCMedia.
// * \param aMedia The media resource that has had a sub item removed from.
// * \param childMedia The sub item removed.
// * \param index The previous location of the recently removed sub item.
// */
// - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;

101 102
@optional

103 104 105 106 107 108
/**
 * Delegate method called whenever the meta has changed for the receiver.
 * \param aMedia The media resource whose meta data has been changed.
 * \param oldValue The old meta data value.
 * \param key The key of the value that was changed.
 */
109 110 111 112 113 114 115 116
- (void)media:(VLCMedia *)aMedia metaValueChangedFrom:(id)oldValue forKey:(NSString *)key __attribute__((deprecated));

/**
 * Delegate method called whenever the media's meta data was changed for whatever reason
 * \note this is called more often than mediaDidFinishParsing, so it may be less efficient
 * \param aMedia The media resource whose meta data has been changed.
 */
- (void)mediaMetaDataDidChange:(VLCMedia *)aMedia;
Pierre's avatar
Pierre committed
117 118 119 120 121 122 123

/**
 * Delegate method called whenever the media was parsed.
 * \param aMedia The media resource whose meta data has been changed.
 */

- (void)mediaDidFinishParsing:(VLCMedia *)aMedia;
124 125 126
@end

/**
Pierre's avatar
Pierre committed
127 128
 * Defines files and streams as a managed object.  Each media object can be
 * administered seperately.  VLCMediaPlayer or VLCMediaList must be used
129 130
 * to execute the appropriate playback functions.
 * \see VLCMediaPlayer
131
 * \see VLCMediaList
132 133 134
 */
@interface VLCMedia : NSObject

135
/* Factories */
136
/**
137
 * Manufactures a new VLCMedia object using the URL specified.
138
 * \param anURL URL to media to be accessed.
139
 * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
140 141
 * \see initWithMediaURL
 */
James Dumay's avatar
James Dumay committed
142
+ (instancetype)mediaWithURL:(NSURL *)anURL;
143 144 145 146

/**
 * Manufactures a new VLCMedia object using the path specified.
 * \param aPath Path to the media to be accessed.
147
 * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
148 149
 * \see initWithPath
 */
James Dumay's avatar
James Dumay committed
150
+ (instancetype)mediaWithPath:(NSString *)aPath;
151

152 153 154 155 156 157 158
/**
 * TODO
 * \param aName TODO
 * \return a new VLCMedia object, only if there were no errors.  This object
 * will be automatically released.
 * \see initAsNodeWithName
 */
James Dumay's avatar
James Dumay committed
159
+ (instancetype)mediaAsNodeWithName:(NSString *)aName;
160 161 162

/* Initializers */
/**
Pierre's avatar
Pierre committed
163
 * Initializes a new VLCMedia object to use the specified URL.
164 165 166
 * \param aPath Path to media to be accessed.
 * \return A new VLCMedia object, only if there were no errors.
 */
167
- (instancetype)initWithURL:(NSURL *)anURL;
168 169

/**
Pierre's avatar
Pierre committed
170
 * Initializes a new VLCMedia object to use the specified path.
171
 * \param aPath Path to media to be accessed.
172 173
 * \return A new VLCMedia object, only if there were no errors.
 */
James Dumay's avatar
James Dumay committed
174
- (instancetype)initWithPath:(NSString *)aPath;
175 176 177 178 179 180

/**
 * TODO
 * \param aName TODO
 * \return A new VLCMedia object, only if there were no errors.
 */
181
- (instancetype)initAsNodeWithName:(NSString *)aName;
182 183

/**
Pierre's avatar
Pierre committed
184
 * Returns an NSComparisonResult value that indicates the lexical ordering of
185 186
 * the receiver and a given meda.
 * \param media The media with which to compare with the receiver.
Pierre's avatar
Pierre committed
187 188 189
 * \return NSOrderedAscending if the URL of the receiver precedes media in
 * lexical ordering, NSOrderedSame if the URL of the receiver and media are
 * equivalent in lexical value, and NSOrderedDescending if the URL of the
190 191 192 193 194 195
 * receiver follows media. If media is nil, returns NSOrderedDescending.
 */
- (NSComparisonResult)compare:(VLCMedia *)media;

/* Properties */
/**
196
 * Receiver's delegate.
197
 */
198
@property (nonatomic, weak) id<VLCMediaDelegate> delegate;
199 200

/**
201 202 203
 * A VLCTime object describing the length of the media resource, only if it is
 * available.  Use lengthWaitUntilDate: to wait for a specified length of time.
 * \see lengthWaitUntilDate
204
 */
205
@property (nonatomic, readwrite, strong) VLCTime * length;
206 207 208 209 210 211 212 213 214 215 216

/**
 * Returns a VLCTime object describing the length of the media resource,
 * however, this is a blocking operation and will wait until the preparsing is
 * completed before returning anything.
 * \param aDate Time for operation to wait until, if there are no results
 * before specified date then nil is returned.
 * \return The length of the media resource, nil if it couldn't wait for it.
 */
- (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;

217
/**
Pierre's avatar
Pierre committed
218
 * Determines if the media has already been preparsed.
219
 */
220
@property (nonatomic, readonly) BOOL isParsed;
221 222

/**
223
 * The URL for the receiver's media resource.
224
 */
225
@property (nonatomic, readonly, strong) NSURL * url;
226 227

/**
228
 * The receiver's sub list.
229
 */
230
@property (nonatomic, readonly, strong) VLCMediaList * subitems;
231

232 233 234 235 236 237 238 239 240 241 242 243 244 245 246 247 248 249 250 251
/**
 * get meta property for key
 * \note for performance reasons, fetching the metaDictionary will be faster!
 * \see metaDictionary
 * \see dictionary keys above
 */
- (NSString *)metadataForKey:(NSString *)key;

/**
 * set meta property for key
 * \param metadata to set as NSString
 * \param metadata key
 * \see dictionary keys above
 */
- (void)setMetadata:(NSString *)data forKey:(NSString *)key;

/**
 * Save the previously changed metadata
 * \return true if saving was successful
 */
James Dumay's avatar
James Dumay committed
252
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL saveMetadata;
253

254
/**
255
 * The receiver's meta data as a NSDictionary object.
256
 */
257
@property (nonatomic, readonly, copy) NSDictionary * metaDictionary;
258 259

/**
260
 * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
261
 */
262
@property (nonatomic, readonly) VLCMediaState state;
263

264 265 266
/**
 * returns a bool whether is the media is expected to play fluently on this
 * device or not. It always returns YES on a Mac.*/
James Dumay's avatar
James Dumay committed
267
@property (NS_NONATOMIC_IOSONLY, getter=isMediaSizeSuitableForDevice, readonly) BOOL mediaSizeSuitableForDevice;
268

Pierre's avatar
Pierre committed
269 270 271 272 273 274 275
/**
 * Tracks information NSDictionary Possible Keys
 */

/**
 * \returns a NSNumber
 */
276
extern NSString *const VLCMediaTracksInformationCodec;
Pierre's avatar
Pierre committed
277 278 279 280

/**
 * \returns a NSNumber
 */
281
extern NSString *const VLCMediaTracksInformationId;
Pierre's avatar
Pierre committed
282 283 284 285 286 287 288
/**
 * \returns a NSString
 * \see VLCMediaTracksInformationTypeAudio
 * \see VLCMediaTracksInformationTypeVideo
 * \see VLCMediaTracksInformationTypeText
 * \see VLCMediaTracksInformationTypeUnknown
 */
289
extern NSString *const VLCMediaTracksInformationType;
Pierre's avatar
Pierre committed
290 291 292 293

/**
 * \returns a NSNumber
 */
294
extern NSString *const VLCMediaTracksInformationCodecProfile;
Pierre's avatar
Pierre committed
295 296 297
/**
 * \returns a NSNumber
 */
298
extern NSString *const VLCMediaTracksInformationCodecLevel;
Pierre's avatar
Pierre committed
299 300

/**
301 302
 * \returns the bitrate as NSNumber
 */
303
extern NSString *const VLCMediaTracksInformationBitrate;
304 305 306
/**
 * \returns the language as NSString
 */
307
extern NSString *const VLCMediaTracksInformationLanguage;
308 309 310
/**
 * \returns the description as NSString
 */
311
extern NSString *const VLCMediaTracksInformationDescription;
312 313 314

/**
 * \returns the audio channel number as NSNumber
Pierre's avatar
Pierre committed
315
 */
316
extern NSString *const VLCMediaTracksInformationAudioChannelsNumber;
Pierre's avatar
Pierre committed
317 318 319
/**
 * \returns the audio rate as NSNumber
 */
320
extern NSString *const VLCMediaTracksInformationAudioRate;
Pierre's avatar
Pierre committed
321 322 323 324

/**
 * \returns the height as NSNumber
 */
325
extern NSString *const VLCMediaTracksInformationVideoHeight;
Pierre's avatar
Pierre committed
326 327 328
/**
 * \returns the width as NSNumber
 */
329
extern NSString *const VLCMediaTracksInformationVideoWidth;
Pierre's avatar
Pierre committed
330

331 332 333
/**
 * \returns the source aspect ratio as NSNumber
 */
334
extern NSString *const VLCMediaTracksInformationSourceAspectRatio;
335 336 337
/**
 * \returns the source aspect ratio denominator as NSNumber
 */
338
extern NSString *const VLCMediaTracksInformationSourceAspectRatioDenominator;
339 340 341 342

/**
 * \returns the frame rate as NSNumber
 */
343
extern NSString *const VLCMediaTracksInformationFrameRate;
344 345 346
/**
 * \returns the frame rate denominator as NSNumber
 */
347
extern NSString *const VLCMediaTracksInformationFrameRateDenominator;
348 349 350 351

/**
 * \returns the text encoding as NSString
 */
352
extern NSString *const VLCMediaTracksInformationTextEncoding;
353

Pierre's avatar
Pierre committed
354 355 356 357
/**
 * Tracks information NSDictionary values for
 * VLCMediaTracksInformationType
 */
358 359 360 361
extern NSString *const VLCMediaTracksInformationTypeAudio;
extern NSString *const VLCMediaTracksInformationTypeVideo;
extern NSString *const VLCMediaTracksInformationTypeText;
extern NSString *const VLCMediaTracksInformationTypeUnknown;
Pierre's avatar
Pierre committed
362 363 364 365 366

/**
 * Returns the tracks information.
 *
 * This is an array of NSDictionary representing each track.
367
 * It can contain the following keys:
Pierre's avatar
Pierre committed
368 369 370 371 372 373 374 375
 *
 * \see VLCMediaTracksInformationCodec
 * \see VLCMediaTracksInformationId
 * \see VLCMediaTracksInformationType
 *
 * \see VLCMediaTracksInformationCodecProfile
 * \see VLCMediaTracksInformationCodecLevel
 *
376 377 378 379
 * \see VLCMediaTracksInformationBitrate
 * \see VLCMediaTracksInformationLanguage
 * \see VLCMediaTracksInformationDescription
 *
Pierre's avatar
Pierre committed
380 381 382 383 384
 * \see VLCMediaTracksInformationAudioChannelsNumber
 * \see VLCMediaTracksInformationAudioRate
 *
 * \see VLCMediaTracksInformationVideoHeight
 * \see VLCMediaTracksInformationVideoWidth
385 386 387 388 389 390 391 392
 *
 * \see VLCMediaTracksInformationSourceAspectRatio
 * \see VLCMediaTracksInformationSourceAspectDenominator
 *
 * \see VLCMediaTracksInformationFrameRate
 * \see VLCMediaTracksInformationFrameRateDenominator
 *
 * \see VLCMediaTracksInformationTextEncoding
Pierre's avatar
Pierre committed
393 394
 */

James Dumay's avatar
James Dumay committed
395
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *tracksInformation;
Pierre's avatar
Pierre committed
396 397 398 399 400 401 402 403 404 405 406 407

/**
 * Start asynchronously to parse the media.
 * This will attempt to fetch the meta data and tracks information.
 *
 * This is automatically done when an accessor requiring parsing
 * is called.
 *
 * \see -[VLCMediaDelegate mediaDidFinishParsing:]
 */
- (void)parse;

408 409 410 411 412 413
/**
 * Trigger a synchronous parsing of the media
 * the selector won't return until parsing finished
 */
- (void)synchronousParse;

414
/**
415 416 417 418 419 420
 * Add options to the media, that will be used to determine how
 * VLCMediaPlayer will read the media. This allow to use VLC advanced
 * reading/streaming options in a per-media basis
 *
 * The options are detailed in vlc --long-help, for instance "--sout-all"
 * And on the web: http://wiki.videolan.org/VLC_command-line_help
421
*/
422 423
- (void) addOptions:(NSDictionary*) options;

424 425 426 427 428
/**
 * Getter for statistics information
 * Returns a NSDictionary with NSNumbers for values.
 *
 */
James Dumay's avatar
James Dumay committed
429
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSDictionary *stats;
430

431 432 433 434 435 436
#pragma mark - individual stats

/**
 * returns the number of bytes read by the current input module
 * \return a NSInteger with the raw number of bytes
 */
James Dumay's avatar
James Dumay committed
437
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfReadBytesOnInput;
438 439 440 441
/**
 * returns the current input bitrate. may be 0 if the buffer is full
 * \return a float of the current input bitrate
 */
James Dumay's avatar
James Dumay committed
442
@property (NS_NONATOMIC_IOSONLY, readonly) float inputBitrate;
443 444 445 446 447

/**
 * returns the number of bytes read by the current demux module
 * \return a NSInteger with the raw number of bytes
 */
James Dumay's avatar
James Dumay committed
448
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfReadBytesOnDemux;
449 450 451 452
/**
 * returns the current demux bitrate. may be 0 if the buffer is empty
 * \return a float of the current demux bitrate
 */
James Dumay's avatar
James Dumay committed
453
@property (NS_NONATOMIC_IOSONLY, readonly) float demuxBitrate;
454 455 456 457 458

/**
 * returns the total number of decoded video blocks in the current media session
 * \return a NSInteger with the total number of decoded blocks
 */
James Dumay's avatar
James Dumay committed
459
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfDecodedVideoBlocks;
460 461 462 463
/**
 * returns the total number of decoded audio blocks in the current media session
 * \return a NSInteger with the total number of decoded blocks
 */
James Dumay's avatar
James Dumay committed
464
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfDecodedAudioBlocks;
465 466 467 468 469

/**
 * returns the total number of displayed pictures during the current media session
 * \return a NSInteger with the total number of displayed pictures
 */
James Dumay's avatar
James Dumay committed
470
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfDisplayedPictures;
471 472 473 474
/**
 * returns the total number of pictures lost during the current media session
 * \return a NSInteger with the total number of lost pictures
 */
James Dumay's avatar
James Dumay committed
475
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfLostPictures;
476 477 478 479 480

/**
 * returns the total number of played audio buffers during the current media session
 * \return a NSInteger with the total number of played audio buffers
 */
James Dumay's avatar
James Dumay committed
481
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfPlayedAudioBuffers;
482 483 484 485
/**
 * returns the total number of audio buffers lost during the current media session
 * \return a NSInteger with the total number of displayed pictures
 */
James Dumay's avatar
James Dumay committed
486
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfLostAudioBuffers;
487 488 489 490 491

/**
 * returns the total number of packets sent during the current media session
 * \return a NSInteger with the total number of sent packets
 */
James Dumay's avatar
James Dumay committed
492
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfSentPackets;
493 494 495 496
/**
 * returns the total number of raw bytes sent during the current media session
 * \return a NSInteger with the total number of sent bytes
 */
James Dumay's avatar
James Dumay committed
497
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfSentBytes;
498 499 500 501
/**
 * returns the current bitrate of sent bytes
 * \return a float of the current bitrate of sent bits
 */
James Dumay's avatar
James Dumay committed
502
@property (NS_NONATOMIC_IOSONLY, readonly) float streamOutputBitrate;
503 504 505 506 507
/**
 * returns the total number of corrupted data packets during current sout session
 * \note value is 0 on non-stream-output operations
 * \return a NSInteger with the total number of corrupted data packets
 */
James Dumay's avatar
James Dumay committed
508
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfCorruptedDataPackets;
509 510 511 512 513
/**
 * returns the total number of discontinuties during current sout session
 * \note value is 0 on non-stream-output operations
 * \return a NSInteger with the total number of discontinuties
 */
James Dumay's avatar
James Dumay committed
514
@property (NS_NONATOMIC_IOSONLY, readonly) NSInteger numberOfDiscontinuties;
515

516
@end