projects/macosx/framework/Headers/Public/VLCMedia.h

   1 /*****************************************************************************
   2  * VLCMedia.h: VLCKit.framework VLCMedia header
   3  *****************************************************************************
   4  * Copyright (C) 2007 Pierre d'Herbemont
   5  * Copyright (C) 2007 the VideoLAN team
   6  * $Id$
   7  *
   8  * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
   9  *
  10  * This program is free software; you can redistribute it and/or modify
  11  * it under the terms of the GNU General Public License as published by
  12  * the Free Software Foundation; either version 2 of the License, or
  13  * (at your option) any later version.
  14  *
  15  * This program is distributed in the hope that it will be useful,
  16  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  17  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  18  * GNU General Public License for more details.
  19  *
  20  * You should have received a copy of the GNU General Public License
  21  * along with this program; if not, write to the Free Software
  22  * Foundation, Inc., 51 Franklin Street, Fifth Floor, Boston MA 02110-1301, USA.
  23  *****************************************************************************/
  24
  25 #import <Foundation/Foundation.h>
  26 #import "VLCMediaList.h"
  27 #import "VLCTime.h"
  28
  29 /* Meta Dictionary Keys */
  30 /**
  31  * Standard dictionary keys for retreiving meta data.
  32  */
  33 extern NSString * VLCMetaInformationTitle;          /* NSString */
  34 extern NSString * VLCMetaInformationArtist;         /* NSString */
  35 extern NSString * VLCMetaInformationGenre;          /* NSString */
  36 extern NSString * VLCMetaInformationCopyright;      /* NSString */
  37 extern NSString * VLCMetaInformationAlbum;          /* NSString */
  38 extern NSString * VLCMetaInformationTrackNumber;    /* NSString */
  39 extern NSString * VLCMetaInformationDescription;    /* NSString */
  40 extern NSString * VLCMetaInformationRating;         /* NSString */
  41 extern NSString * VLCMetaInformationDate;           /* NSString */
  42 extern NSString * VLCMetaInformationSetting;        /* NSString */
  43 extern NSString * VLCMetaInformationURL;            /* NSString */
  44 extern NSString * VLCMetaInformationLanguage;       /* NSString */
  45 extern NSString * VLCMetaInformationNowPlaying;     /* NSString */
  46 extern NSString * VLCMetaInformationPublisher;      /* NSString */
  47 extern NSString * VLCMetaInformationEncodedBy;      /* NSString */
  48 extern NSString * VLCMetaInformationArtworkURL;     /* NSString */
  49 extern NSString * VLCMetaInformationArtwork;        /* NSImage  */
  50 extern NSString * VLCMetaInformationTrackID;        /* NSString */
  51
  52 /* Notification Messages */
  53 /**
  54  * Available notification messages.
  55  */
  56 extern NSString * VLCMediaMetaChanged;  //< Notification message for when the media's meta data has changed
  57
  58 // Forward declarations, supresses compiler error messages
  59 @class VLCMediaList;
  60 @class VLCMedia;
  61
  62 typedef enum VLCMediaState
  63 {
  64     VLCMediaStateNothingSpecial,        //< Nothing
  65     VLCMediaStateBuffering,             //< Stream is buffering
  66     VLCMediaStatePlaying,               //< Stream is playing
  67     VLCMediaStateError,                 //< Can't be played because an error occured
  68 } VLCMediaState;
  69
  70 /**
  71  * Informal protocol declaration for VLCMedia delegates.  Allows data changes to be
  72  * trapped.
  73  */
  74 @protocol VLCMediaDelegate
  75 // TODO: SubItemAdded/SubItemRemoved implementation.  Not sure if we really want to implement this.
  76 ///**
  77 // * Delegate method called whenever a sub item has been added to the specified VLCMedia.
  78 // * \param aMedia The media resource that has received the new sub item.
  79 // * \param childMedia The new sub item added.
  80 // * \param index Location of the new subitem in the aMedia's sublist.
  81 // */
  82 // - (void)media:(VLCMedia *)media addedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
  83
  84 ///**
  85 // * Delegate method called whenever a sub item has been removed from the specified VLCMedia.
  86 // * \param aMedia The media resource that has had a sub item removed from.
  87 // * \param childMedia The sub item removed.
  88 // * \param index The previous location of the recently removed sub item.
  89 // */
  90 // - (void)media:(VLCMedia *)aMedia removedSubItem:(VLCMedia *)childMedia atIndex:(int)index;
  91
  92 /**
  93  * Delegate method called whenever the meta has changed for the receiver.
  94  * \param aMedia The media resource whose meta data has been changed.
  95  * \param oldValue The old meta data value.
  96  * \param key The key of the value that was changed.
  97  */
  98 - (void)media:(VLCMedia *)aMedia metaValueChangedFrom:(id)oldValue forKey:(NSString *)key;
  99
 100 /**
 101  * Delegate method called whenever the media was parsed.
 102  * \param aMedia The media resource whose meta data has been changed.
 103  */
 104
 105 - (void)mediaDidFinishParsing:(VLCMedia *)aMedia;
 106 @end
 107
 108 /**
 109  * Defines files and streams as a managed object.  Each media object can be
 110  * administered seperately.  VLCMediaPlayer or VLCMediaList must be used
 111  * to execute the appropriate playback functions.
 112  * \see VLCMediaPlayer
 113  * \see VLCMediaList
 114  */
 115 @interface VLCMedia : NSObject
 116 {
 117     void *                p_md;              //< Internal media descriptor instance
 118     NSURL *               url;               //< URL (MRL) for this media resource
 119     VLCMediaList *        subitems;          //< Sub list of items
 120     VLCTime *             length;            //< Cached duration of the media
 121     NSMutableDictionary * metaDictionary;    //< Meta data storage
 122     id                    delegate;          //< Delegate object
 123     BOOL                  isArtFetched;      //< Value used to determine of the artwork has been parsed
 124     BOOL                  areOthersMetaFetched; //< Value used to determine of the other meta has been parsed
 125     BOOL                  isArtURLFetched;   //< Value used to determine of the other meta has been preparsed
 126     VLCMediaState         state;             //< Current state of the media
 127     BOOL                  isParsed;
 128 }
 129
 130 /* Factories */
 131 /**
 132  * Manufactures a new VLCMedia object using the URL specified.
 133  * \param anURL URL to media to be accessed.
 134  * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
 135  * \see initWithMediaURL
 136  */
 137 + (id)mediaWithURL:(NSURL *)anURL;
 138
 139 /**
 140  * Manufactures a new VLCMedia object using the path specified.
 141  * \param aPath Path to the media to be accessed.
 142  * \return A new VLCMedia object, only if there were no errors.  This object will be automatically released.
 143  * \see initWithPath
 144  */
 145 + (id)mediaWithPath:(NSString *)aPath;
 146
 147 /**
 148  * TODO
 149  * \param aName TODO
 150  * \return a new VLCMedia object, only if there were no errors.  This object
 151  * will be automatically released.
 152  * \see initAsNodeWithName
 153  */
 154 + (id)mediaAsNodeWithName:(NSString *)aName;
 155
 156 /* Initializers */
 157 /**
 158  * Initializes a new VLCMedia object to use the specified URL.
 159  * \param aPath Path to media to be accessed.
 160  * \return A new VLCMedia object, only if there were no errors.
 161  */
 162 - (id)initWithURL:(NSURL *)anURL;
 163
 164 /**
 165  * Initializes a new VLCMedia object to use the specified path.
 166  * \param aPath Path to media to be accessed.
 167  * \return A new VLCMedia object, only if there were no errors.
 168  */
 169 - (id)initWithPath:(NSString *)aPath;
 170
 171 /**
 172  * TODO
 173  * \param aName TODO
 174  * \return A new VLCMedia object, only if there were no errors.
 175  */
 176 - (id)initAsNodeWithName:(NSString *)aName;
 177
 178 /**
 179  * Returns an NSComparisonResult value that indicates the lexical ordering of
 180  * the receiver and a given meda.
 181  * \param media The media with which to compare with the receiver.
 182  * \return NSOrderedAscending if the URL of the receiver precedes media in
 183  * lexical ordering, NSOrderedSame if the URL of the receiver and media are
 184  * equivalent in lexical value, and NSOrderedDescending if the URL of the
 185  * receiver follows media. If media is nil, returns NSOrderedDescending.
 186  */
 187 - (NSComparisonResult)compare:(VLCMedia *)media;
 188
 189 /* Properties */
 190 /**
 191  * Receiver's delegate.
 192  */
 193 @property (assign) id delegate;
 194
 195 /**
 196  * A VLCTime object describing the length of the media resource, only if it is
 197  * available.  Use lengthWaitUntilDate: to wait for a specified length of time.
 198  * \see lengthWaitUntilDate
 199  */
 200 @property (retain, readonly) VLCTime * length;
 201
 202 /**
 203  * Returns a VLCTime object describing the length of the media resource,
 204  * however, this is a blocking operation and will wait until the preparsing is
 205  * completed before returning anything.
 206  * \param aDate Time for operation to wait until, if there are no results
 207  * before specified date then nil is returned.
 208  * \return The length of the media resource, nil if it couldn't wait for it.
 209  */
 210 - (VLCTime *)lengthWaitUntilDate:(NSDate *)aDate;
 211
 212 /**
 213  * Determines if the media has already been preparsed.
 214  */
 215 @property (readonly) BOOL isParsed;
 216
 217 /**
 218  * The URL for the receiver's media resource.
 219  */
 220 @property (retain, readonly) NSURL * url;
 221
 222 /**
 223  * The receiver's sub list.
 224  */
 225 @property (retain, readonly) VLCMediaList * subitems;
 226
 227 /**
 228  * The receiver's meta data as a NSDictionary object.
 229  */
 230 @property (retain, readonly) NSDictionary * metaDictionary;
 231
 232 /**
 233  * The receiver's state, such as Playing, Error, NothingSpecial, Buffering.
 234  */
 235 @property (readonly) VLCMediaState state;
 236
 237 /**
 238  * Sets a value of the metaDictionary
 239  */
 240 - (void)setValue:(id)value forMeta:(NSString *)VLCMetaInformation;
 241
 242
 243 /**
 244  * Tracks information NSDictionary Possible Keys
 245  */
 246
 247 /**
 248  * \returns a NSNumber
 249  */
 250 extern NSString *VLCMediaTracksInformationCodec;
 251
 252 /**
 253  * \returns a NSNumber
 254  */
 255 extern NSString *VLCMediaTracksInformationId;
 256 /**
 257  * \returns a NSString
 258  * \see VLCMediaTracksInformationTypeAudio
 259  * \see VLCMediaTracksInformationTypeVideo
 260  * \see VLCMediaTracksInformationTypeText
 261  * \see VLCMediaTracksInformationTypeUnknown
 262  */
 263 extern NSString *VLCMediaTracksInformationType;
 264
 265 /**
 266  * \returns a NSNumber
 267  */
 268 extern NSString *VLCMediaTracksInformationCodecProfile;
 269 /**
 270  * \returns a NSNumber
 271  */
 272 extern NSString *VLCMediaTracksInformationCodecLevel;
 273
 274 /**
 275  * \returns the audio channels number as NSNumber
 276  */
 277 extern NSString *VLCMediaTracksInformationAudioChannelsNumber;
 278 /**
 279  * \returns the audio rate as NSNumber
 280  */
 281 extern NSString *VLCMediaTracksInformationAudioRate;
 282
 283 /**
 284  * \returns the height as NSNumber
 285  */
 286 extern NSString *VLCMediaTracksInformationVideoHeight;
 287 /**
 288  * \returns the width as NSNumber
 289  */
 290 extern NSString *VLCMediaTracksInformationVideoWidth;
 291
 292 /**
 293  * Tracks information NSDictionary values for
 294  * VLCMediaTracksInformationType
 295  */
 296 extern NSString *VLCMediaTracksInformationTypeAudio;
 297 extern NSString *VLCMediaTracksInformationTypeVideo;
 298 extern NSString *VLCMediaTracksInformationTypeText;
 299 extern NSString *VLCMediaTracksInformationTypeUnknown;
 300
 301
 302 /**
 303  * Returns the tracks information.
 304  *
 305  * This is an array of NSDictionary representing each track.
 306  * It can contains the following keys:
 307  *
 308  * \see VLCMediaTracksInformationCodec
 309  * \see VLCMediaTracksInformationId
 310  * \see VLCMediaTracksInformationType
 311  *
 312  * \see VLCMediaTracksInformationCodecProfile
 313  * \see VLCMediaTracksInformationCodecLevel
 314  *
 315  * \see VLCMediaTracksInformationAudioChannelsNumber
 316  * \see VLCMediaTracksInformationAudioRate
 317  *
 318  * \see VLCMediaTracksInformationVideoHeight
 319  * \see VLCMediaTracksInformationVideoWidth
 320  */
 321
 322 - (NSArray *)tracksInformation;
 323
 324 /**
 325  * Start asynchronously to parse the media.
 326  * This will attempt to fetch the meta data and tracks information.
 327  *
 328  * This is automatically done when an accessor requiring parsing
 329  * is called.
 330  *
 331  * \see -[VLCMediaDelegate mediaDidFinishParsing:]
 332  */
 333 - (void)parse;
 334
 335 @end