Commit efd79571 authored by Felix Paul Kühne's avatar Felix Paul Kühne
Browse files

Add complete documentation

parent bc2e3177
......@@ -28,10 +28,25 @@
*/
@interface VLCExtension : NSObject
/**
* initializer for wrapper class
* \param instance the extension_t instance to init the wrapper with
*/
- (instancetype)initWithInstance:(struct extension_t *)instance NS_DESIGNATED_INITIALIZER; // FIXME: Should be internal
/**
* the extension instance used to init the wrapper with
*/
@property (NS_NONATOMIC_IOSONLY, readonly) struct extension_t *instance; // FIXME: Should be internal
/**
* technical name of the extension
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSString *name;
/**
* user-visible name of the extension
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSString *title;
@end
......@@ -30,10 +30,25 @@
*/
@interface VLCExtensionsManager : NSObject
/**
* singleton manager instance
*/
+ (VLCExtensionsManager *)sharedManager;
/**
* list of available extensions
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *extensions;
/**
* start execution of a given extension instance
* \param extension the extension to run
*/
- (void)runExtension:(VLCExtension *)extension;
/**
* player instance to use with the extensions
*/
@property (readwrite, strong) VLCMediaPlayer *mediaPlayer;
@end
......@@ -107,6 +107,10 @@
*/
- (void)setApplicationIdentifier:(NSString *)identifier withVersion:(NSString *)version andApplicationIconName:(NSString *)icon;
/**
* the libvlc instance wrapped by the VLCLibrary instance
* \note if you want to use it, you are most likely wrong (or want to add a proper ObjC API)
*/
@property (nonatomic, assign) void *instance;
@end
......@@ -81,22 +81,6 @@ typedef NS_ENUM(NSInteger, VLCMediaState) {
* trapped.
*/
@protocol VLCMediaDelegate <NSObject>
// 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;
@optional
......@@ -180,6 +164,9 @@ typedef NS_ENUM(NSInteger, VLCMediaState) {
*/
- (instancetype)initAsNodeWithName:(NSString *)aName;
/**
* list of possible media types that could be returned by "mediaType"
*/
typedef NS_ENUM(NSUInteger, VLCMediaType) {
VLCMediaTypeUnknown,
VLCMediaTypeFile,
......@@ -235,6 +222,9 @@ typedef NS_ENUM(NSUInteger, VLCMediaType) {
*/
@property (nonatomic, readonly) BOOL isParsed __attribute__((deprecated));
/**
* list of possible parsed states returnable by parsedStatus
*/
typedef NS_ENUM(unsigned, VLCMediaParsedStatus)
{
VLCMediaParsedStatusInit = 0,
......@@ -397,12 +387,20 @@ extern NSString *const VLCMediaTracksInformationFrameRateDenominator;
extern NSString *const VLCMediaTracksInformationTextEncoding;
/**
* Tracks information NSDictionary values for
* VLCMediaTracksInformationType
* audio track information NSDictionary value for VLCMediaTracksInformationType
*/
extern NSString *const VLCMediaTracksInformationTypeAudio;
/**
* video track information NSDictionary value for VLCMediaTracksInformationType
*/
extern NSString *const VLCMediaTracksInformationTypeVideo;
/**
* text / subtitles track information NSDictionary value for VLCMediaTracksInformationType
*/
extern NSString *const VLCMediaTracksInformationTypeText;
/**
* unknown track information NSDictionary value for VLCMediaTracksInformationType
*/
extern NSString *const VLCMediaTracksInformationTypeUnknown;
/**
......@@ -466,6 +464,10 @@ enum {
VLCMediaFetchLocal = 0x02,
VLCMediaFetchNetwork = 0x04,
};
/**
* enum of available options for use with parseWithOptions
* \note you may pipe multiple values for the single parameter
*/
typedef int VLCMediaParsingOptions;
/**
......
......@@ -51,6 +51,10 @@ extern NSString *const VLCMediaDiscovererCategory;
@interface VLCMediaDiscoverer : NSObject
/**
* The library instance used by the discoverers
* \note unless for debug, you are wrong if you want to use this selector
*/
@property (nonatomic, readonly) VLCLibrary *libraryInstance;
/**
......
......@@ -27,14 +27,18 @@
@class VLCMediaList;
/**
* TODO: Documentation
* media library stub
*/
@interface VLCMediaLibrary : NSObject
/* Factories */
/**
* library singleton
*/
+ (VLCMediaLibrary*)sharedMediaLibrary;
/* Properties */
/**
* list of all media
*/
@property (nonatomic, readonly, strong) VLCMediaList * allMedia;
@end
......@@ -26,8 +26,13 @@
#import <Foundation/Foundation.h>
#import "VLCMedia.h"
/* Notification Messages */
/**
* notification name if a list item was added
*/
extern NSString *const VLCMediaListItemAdded;
/**
* notification name if a list item was deleted
*/
extern NSString *const VLCMediaListItemDeleted;
@class VLCMedia;
......@@ -61,6 +66,12 @@ extern NSString *const VLCMediaListItemDeleted;
*/
@interface VLCMediaList : NSObject
/**
* initializer with a set of VLCMedia instances
* \param array the NSArray of VLCMedia instances
* \return instance of VLCMediaList equipped with the VLCMedia instances
* \see VLCMedia
*/
- (instancetype)initWithArray:(NSArray *)array;
/* Operations */
......
......@@ -37,10 +37,14 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
};
/**
* A media list player, which eases the use of playlists */
* A media list player, which eases the use of playlists
*/
@interface VLCMediaListPlayer : NSObject
/**
* setter/getter for mediaList to play within the player
* \note This list is erased when setting a rootMedia on the list player instance
*/
@property (readwrite) VLCMediaList *mediaList;
/**
......@@ -49,24 +53,51 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
* Setting mediaList will erase rootMedia.
*/
@property (readwrite) VLCMedia *rootMedia;
/**
* the media player instance used for playback by the list player
*/
@property (readonly) VLCMediaPlayer *mediaPlayer;
/**
* initializer with a certain drawable
* \note drawable can also be set later
*/
- (instancetype)initWithDrawable:(id)drawable;
/**
* initializer with a custom options
* \note This is will initialize a new VLCLibrary instance, which WILL have a major memory impact
*/
- (instancetype)initWithOptions:(NSArray *)options;
/**
* initializer with a certain drawable and options
* \see initWithDrawable
* \see initWithOptions
*/
- (instancetype)initWithOptions:(NSArray *)options andDrawable:(id)drawable;
/**
* Basic play, pause and stop are here. For other methods, use the mediaPlayer.
* start playback
*/
- (void)play;
/**
* pause playback
*/
- (void)pause;
/**
* stop playback
*/
- (void)stop;
/**
* previous, next, play item at index
* play next item
* \returns YES on success, NO if there is no such item
*/
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL next;
/**
* play previous item
* \returns YES on success, NO if there is no such item
*/
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL previous;
/**
......@@ -84,7 +115,6 @@ typedef NS_ENUM(NSInteger, VLCRepeatMode) {
* Playmode selection (don't repeat anything, repeat one, repeat all)
* See VLCRepeatMode.
*/
@property (readwrite) VLCRepeatMode repeatMode;
/**
......
......@@ -132,15 +132,42 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
*/
@interface VLCMediaPlayer : NSObject
/**
* the library instance in use by the player instance
*/
@property (nonatomic, readonly) VLCLibrary *libraryInstance;
/**
* the delegate object implementing the optional protocol
*/
@property (weak, nonatomic) id<VLCMediaPlayerDelegate> delegate;
#if !TARGET_OS_IPHONE
/* Initializers */
/**
* initialize player with a given video view
* \param aVideoView an instance of VLCVideoView
* \note This initializer is for macOS only
*/
- (instancetype)initWithVideoView:(VLCVideoView *)aVideoView;
/**
* initialize player with a given video layer
* \param aVideoLayer an instance of VLCVideoLayer
* \note This initializer is for macOS only
*/
- (instancetype)initWithVideoLayer:(VLCVideoLayer *)aVideoLayer;
#endif
/**
* initialize player with a given set of options
* \param options an array of private options
* \note This will allocate a new libvlc and VLCLibrary instance, which will have a memory impact
*/
- (instancetype)initWithOptions:(NSArray *)options;
/**
* initialize player with a certain libvlc instance and VLCLibrary
* \param playerInstance the libvlc instance
* \param library the library instance
* \note This is an advanced initializer for very specialized environments
*/
- (instancetype)initWithLibVLCInstance:(void *)playerInstance andLibrary:(VLCLibrary *)library;
/* Video View Options */
......@@ -150,10 +177,24 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
#pragma mark video functionality
#if !TARGET_OS_IPHONE
/**
* set a video view for rendering
* \param aVideoView instance of VLCVideoView
* \note This setter is macOS only
*/
- (void)setVideoView:(VLCVideoView *)aVideoView;
/**
* set a video layer for rendering
* \param aVideoLayer instance of VLCVideoLayer
* \note This setter is macOS only
*/
- (void)setVideoLayer:(VLCVideoLayer *)aVideoLayer;
#endif
/**
* set/retrieve a video view for rendering
* This can be any UIView or NSView or instances of VLCVideoView / VLCVideoLayer if running on macOS
*/
@property (strong) id drawable; /* The videoView or videoLayer */
/**
......@@ -251,6 +292,10 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
*/
@property (nonatomic) float rate;
/**
* an audio controller object
* \return instance of VLCAudio
*/
@property (nonatomic, readonly, weak) VLCAudio * audio;
/* Video Information */
......@@ -285,10 +330,15 @@ extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
/**
* Returns the current position (or time) of the feed.
* \return VLCTIme object with current time.
* \return VLCTime object with current time.
*/
@property (NS_NONATOMIC_IOSONLY, strong) VLCTime *time;
/**
* Returns the current position (or time) of the feed, inversed if a duration is available
* \return VLCTime object with requested time
* \note VLCTime will be a nullTime if no duration can be calculated for the current input
*/
@property (nonatomic, readonly, weak) VLCTime *remainingTime;
#pragma mark -
......@@ -390,14 +440,22 @@ typedef NS_ENUM(unsigned, VLCMediaPlaybackSlaveType)
*/
/**
* Return the current video subtitle index, or
* Return the current chapter index, or
* \return NSNotFound if none is set.
*
* To disable subtitle pass NSNotFound.
*/
@property (readwrite) int currentChapterIndex;
/**
* switch to the previous chapter
*/
- (void)previousChapter;
/**
* switch to the next chapter
*/
- (void)nextChapter;
/**
* returns the number of chapters for a given title
* \param titleIndex the index of the title you are requesting the chapters for
*/
- (int)numberOfChaptersForTitle:(int)titleIndex;
/**
......@@ -406,8 +464,17 @@ typedef NS_ENUM(unsigned, VLCMediaPlaybackSlaveType)
*/
- (NSArray *)chaptersForTitleIndex:(int)titleIndex __attribute__((deprecated));
/**
* dictionary value for the user-facing chapter name
*/
extern NSString *const VLCChapterDescriptionName;
/**
* dictionary value for the chapter's time offset
*/
extern NSString *const VLCChapterDescriptionTimeOffset;
/**
* dictionary value for the chapter's duration
*/
extern NSString *const VLCChapterDescriptionDuration;
/**
......@@ -416,6 +483,9 @@ extern NSString *const VLCChapterDescriptionDuration;
* chapter name, time offset and duration
* \note if no title value is provided, information about the chapters of the current title is returned
* \return array describing the titles in details
* \see VLCChapterDescriptionName
* \see VLCChapterDescriptionTimeOffset
* \see VLCChapterDescriptionDuration
*/
- (NSArray *)chapterDescriptionsOfTitle:(int)titleIndex;
......@@ -424,6 +494,10 @@ extern NSString *const VLCChapterDescriptionDuration;
* \return NSNotFound if none is set.
*/
@property (readwrite) int currentTitleIndex;
/**
* number of titles available for the current media
* \return the number of titles
*/
@property (readonly) int numberOfTitles;
/**
......@@ -437,8 +511,17 @@ extern NSString *const VLCChapterDescriptionDuration;
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titles __attribute__((deprecated));
/**
* dictionary value for the user-facing title name
*/
extern NSString *const VLCTitleDescriptionName;
/**
* dictionary value for the title's duration
*/
extern NSString *const VLCTitleDescriptionDuration;
/**
* dictionary value whether the title is a menu or not
*/
extern NSString *const VLCTitleDescriptionIsMenu;
/**
......@@ -446,6 +529,9 @@ extern NSString *const VLCTitleDescriptionIsMenu;
* an array of all titles of the current media including information
* of name, duration and potential menu state
* \return array describing the titles in details
* \see VLCTitleDescriptionName
* \see VLCTitleDescriptionDuration
* \see VLCTitleDescriptionIsMenu
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titleDescriptions;
......@@ -487,6 +573,10 @@ extern NSString *const VLCTitleDescriptionIsMenu;
#pragma mark -
#pragma mark audio functionality
/**
* sets / returns the current audio channel
* \return the currently set audio channel
*/
@property (NS_NONATOMIC_IOSONLY) int audioChannel;
/**
......@@ -502,7 +592,7 @@ extern NSString *const VLCTitleDescriptionIsMenu;
/**
* Get a list of available equalizer profiles
* \Note Current versions do not allow the addition of further profiles
* \note Current versions do not allow the addition of further profiles
* so you need to handle this in your app.
*
* \return array of equalizer profiles
......@@ -511,7 +601,7 @@ extern NSString *const VLCTitleDescriptionIsMenu;
/**
* Re-set the equalizer to a profile retrieved from the list
* \Note This doesn't enable the Equalizer automagically
* \note This doesn't enable the Equalizer automagically
*/
- (void)resetEqualizerFromProfile:(unsigned)profile;
......@@ -555,6 +645,9 @@ extern NSString *const VLCTitleDescriptionIsMenu;
#pragma mark media handling
/* Media Options */
/**
* The currently media instance set to play
*/
@property (NS_NONATOMIC_IOSONLY, strong) VLCMedia *media;
#pragma mark -
......@@ -692,15 +785,25 @@ extern NSString *const VLCTitleDescriptionIsMenu;
*/
@property (NS_NONATOMIC_IOSONLY, getter=isSeekable, readonly) BOOL seekable;
/**
* property whether the currently playing media can be paused (or not)
* \return BOOL value
*/
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL canPause;
#if TARGET_OS_IPHONE
/**
* Array of taken snapshots of the current video output
* \return a NSArray of UIImage instances
* \note This property is not available to macOS
*/
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *snapshots;
/**
* Get last snapshot available.
* \return an UIImage with the last snapshot available.
* \note return value is nil if there is no snapshot
* \note This property is not available to macOS
*/
@property (NS_NONATOMIC_IOSONLY, readonly) UIImage *lastSnapshot;
#endif
......
......@@ -34,13 +34,44 @@
*/
@interface VLCMediaThumbnailer : NSObject
/**
* initializer
* \param media the media item to thumbnail
* \param delegate the delegate implementing the required protocol
* \return the thumbnailer instance
* \note This will use the default shared library instance
*/
+ (VLCMediaThumbnailer *)thumbnailerWithMedia:(VLCMedia *)media andDelegate:(id<VLCMediaThumbnailerDelegate>)delegate;
/**
* initializer
* \param media the media item to thumbnail
* \param delegate the delegate implementing the required protocol
* \param library a library instance, potentially configured by you in a special way
* \return the thumbnailer instance
*/
+ (VLCMediaThumbnailer *)thumbnailerWithMedia:(VLCMedia *)media delegate:(id<VLCMediaThumbnailerDelegate>)delegate andVLCLibrary:(VLCLibrary *)library;
/**
* Starts the thumbnailing process
*/
- (void)fetchThumbnail;
/**
* delegate object associated with the thumbnailer instance implementing the required protocol
*/
@property (readwrite, weak, nonatomic) id<VLCMediaThumbnailerDelegate> delegate;
/**
* the media object that is being thumbnailed
*/
@property (readwrite, nonatomic) VLCMedia *media;
/**
* The thumbnail created for the media object
*/
@property (readwrite, assign, nonatomic) CGImageRef thumbnail;
/**
* the libvlc instance used for thumbnailing
* \note Whatever you do, using this instance is most likely wrong
*/
@property (readwrite) void * libVLCinstance;
/**
......@@ -73,6 +104,16 @@
*/
@protocol VLCMediaThumbnailerDelegate
@required
/**
* called when the thumbnailing process timed-out
* \param mediaThumbnailer the thumbnailer instance that timed out
* \note The time-out duration depends on various factors outside your control and will not be the same for different media
*/
- (void)mediaThumbnailerDidTimeOut:(VLCMediaThumbnailer *)mediaThumbnailer;
/**
* called when the thumbnailer did successfully created a thumbnail
* \param mediaThumbnailer the thumbnailer instance that was successful
* \param thumbnail the thumbnail that was created
*/
- (void)mediaThumbnailer:(VLCMediaThumbnailer *)mediaThumbnailer didFinishThumbnail:(CGImageRef)thumbnail;
@end
......@@ -29,26 +29,88 @@
*/
@interface VLCTime : NSObject
/* Factories */
/**
* factorize an empty time object
* \return the VLCTime object
*/
+ (VLCTime *)nullTime;
/**
* factorize a time object with a given number object
* \param aNumber the NSNumber object with a time in milliseconds
* \return the VLCTime object
*/
+ (VLCTime *)timeWithNumber:(NSNumber *)aNumber;
/**
* factorize a time object with a given integer
* \param aInt the int with a time in milliseconds
* \return the VLCTime object
*/
+ (VLCTime *)timeWithInt:(int)aInt;
/* Initializers */
/**
* init a time object with a given number object
* \param aNumber the NSNumber object with a time in milliseconds
* \return the VLCTime object
*/
- (instancetype)initWithNumber:(NSNumber *)aNumber;
/**
* init a time object with a given integer
* \param aInt the int with a time in milliseconds
* \return the VLCTime object
*/
- (instancetype)initWithInt:(int)aInt;
/* Properties */
/**
* the current time value as NSNumber
* \return the NSNumber object
*/
@property (nonatomic, readonly) NSNumber * value; ///< Holds, in milliseconds, the VLCTime value
@property (readonly) NSNumber * numberValue; // here for backwards compatibility
/**
* the current time value as NSNumber
* \return the NSNumber object
* \deprecated use value instead