VLCMediaPlayer.h 26.1 KB
Newer Older
1
/*****************************************************************************
2
 * VLCMediaPlayer.h: VLCKit.framework VLCMediaPlayer header
3
 *****************************************************************************
4
 * Copyright (C) 2007-2009 Pierre d'Herbemont
5 6
 * Copyright (C) 2007-2015 VLC authors and VideoLAN
 * Copyright (C) 2009-2015 Felix Paul Kühne
7 8 9
 * $Id$
 *
 * Authors: Pierre d'Herbemont <pdherbemont # videolan.org>
10
 *          Felix Paul Kühne <fkuehne # videolan.org>
11
 *          Soomin Lee <TheHungryBu # gmail.com>
12
 *
13 14 15
 * 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
16 17 18 19
 * (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
20 21
 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
 * GNU Lesser General Public License for more details.
22
 *
23 24 25
 * 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.
26 27
 *****************************************************************************/

Pierre's avatar
Pierre committed
28 29 30
#import <Foundation/Foundation.h>
#if TARGET_OS_IPHONE
# import <CoreGraphics/CoreGraphics.h>
31
# import <UIKit/UIKit.h>
Pierre's avatar
Pierre committed
32
#endif
33
#import "VLCMedia.h"
34
#import "VLCTime.h"
35 36
#import "VLCAudio.h"

37
#if !TARGET_OS_IPHONE
Pierre's avatar
Pierre committed
38 39 40 41
@class VLCVideoView;
@class VLCVideoLayer;
#endif

42
@class VLCLibrary;
Soomin Lee's avatar
Soomin Lee committed
43
@class VLCRendererItem;
44

45
/* Notification Messages */
46 47
extern NSString *const VLCMediaPlayerTimeChanged;
extern NSString *const VLCMediaPlayerStateChanged;
48 49
extern NSString *const VLCMediaPlayerTitleChanged;
extern NSString *const VLCMediaPlayerChapterChanged;
50

51
/**
52
 * VLCMediaPlayerState describes the state of the media player.
53
 */
James Dumay's avatar
James Dumay committed
54
typedef NS_ENUM(NSInteger, VLCMediaPlayerState)
55
{
56 57 58 59 60 61
    VLCMediaPlayerStateStopped,        ///< Player has stopped
    VLCMediaPlayerStateOpening,        ///< Stream is opening
    VLCMediaPlayerStateBuffering,      ///< Stream is buffering
    VLCMediaPlayerStateEnded,          ///< Stream has ended
    VLCMediaPlayerStateError,          ///< Player has generated an error
    VLCMediaPlayerStatePlaying,        ///< Stream is playing
62 63
    VLCMediaPlayerStatePaused,         ///< Stream is paused
    VLCMediaPlayerStateESAdded         ///< Elementary Stream added
64
};
65

66 67 68 69 70 71 72 73 74 75 76 77
/**
 * VLCMediaPlaybackNavigationAction describes actions which can be performed to navigate an interactive title
 */
typedef NS_ENUM(unsigned, VLCMediaPlaybackNavigationAction)
{
    VLCMediaPlaybackNavigationActionActivate = 0,
    VLCMediaPlaybackNavigationActionUp,
    VLCMediaPlaybackNavigationActionDown,
    VLCMediaPlaybackNavigationActionLeft,
    VLCMediaPlaybackNavigationActionRight
};

78 79 80 81 82 83 84 85 86 87
/**
 * VLCMediaPlaybackNavigationAction describes actions which can be performed to navigate an interactive title
 */
typedef NS_ENUM(NSInteger, VLCDeinterlace)
{
    VLCDeinterlaceAuto = -1,
    VLCDeinterlaceOn = 1,
    VLCDeinterlaceOff = 0
};

88
/**
89 90 91
 * Returns the name of the player state as a string.
 * \param state The player state.
 * \return A string containing the name of state. If state is not a valid state, returns nil.
92 93
 */
extern NSString * VLCMediaPlayerStateToString(VLCMediaPlayerState state);
94 95 96 97 98 99

/**
 * Formal protocol declaration for playback delegates.  Allows playback messages
 * to be trapped by delegated objects.
 */
@protocol VLCMediaPlayerDelegate
100

101
@optional
102
/**
103
 * Sent by the default notification center whenever the player's state has changed.
104
 * \details Discussion The value of aNotification is always an VLCMediaPlayerStateChanged notification. You can retrieve
105
 * the VLCMediaPlayer object in question by sending object to aNotification.
106
 */
107
- (void)mediaPlayerStateChanged:(NSNotification *)aNotification;
108 109 110 111 112 113 114

/**
 * Sent by the default notification center whenever the player's time has changed.
 * \details Discussion The value of aNotification is always an VLCMediaPlayerTimeChanged notification. You can retrieve
 * the VLCMediaPlayer object in question by sending object to aNotification.
 */
- (void)mediaPlayerTimeChanged:(NSNotification *)aNotification;
115 116 117 118 119 120 121 122 123 124 125 126 127 128 129

/**
 * Sent by the default notification center whenever the player's title has changed (if any).
 * \details Discussion The value of aNotification is always an VLCMediaPlayerTitleChanged notification. You can retrieve
 * the VLCMediaPlayer object in question by sending object to aNotification.
 * \note this is about a title in the navigation sense, not about metadata
 */
- (void)mediaPlayerTitleChanged:(NSNotification *)aNotification;

/**
 * Sent by the default notification center whenever the player's chapter has changed (if any).
 * \details Discussion The value of aNotification is always an VLCMediaPlayerChapterChanged notification. You can retrieve
 * the VLCMediaPlayer object in question by sending object to aNotification.
 */
- (void)mediaPlayerChapterChanged:(NSNotification *)aNotification;
130

131 132 133 134 135 136 137
/**
 * Sent by the default notification center whenever a new snapshot is taken.
 * \details Discussion The value of aNotification is always an VLCMediaPlayerSnapshotTaken notification. You can retrieve
 * the VLCMediaPlayer object in question by sending object to aNotification.
 */
- (void)mediaPlayerSnapshot:(NSNotification *)aNotification;

138 139
@end

Pierre's avatar
Pierre committed
140

Felix Paul Kühne's avatar
Felix Paul Kühne committed
141 142 143
/**
 * The player base class needed to do any playback
 */
144
@interface VLCMediaPlayer : NSObject
145

146 147 148
/**
 * the library instance in use by the player instance
 */
149
@property (nonatomic, readonly) VLCLibrary *libraryInstance;
150 151 152
/**
 * the delegate object implementing the optional protocol
 */
153
@property (weak, nonatomic) id<VLCMediaPlayerDelegate> delegate;
154

Pierre's avatar
Pierre committed
155
#if !TARGET_OS_IPHONE
156
/* Initializers */
157 158 159 160 161
/**
 * initialize player with a given video view
 * \param aVideoView an instance of VLCVideoView
 * \note This initializer is for macOS only
 */
James Dumay's avatar
James Dumay committed
162
- (instancetype)initWithVideoView:(VLCVideoView *)aVideoView;
163 164 165 166 167
/**
 * initialize player with a given video layer
 * \param aVideoLayer an instance of VLCVideoLayer
 * \note This initializer is for macOS only
 */
James Dumay's avatar
James Dumay committed
168
- (instancetype)initWithVideoLayer:(VLCVideoLayer *)aVideoLayer;
Pierre's avatar
Pierre committed
169
#endif
170 171 172 173 174
/**
 * 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
 */
James Dumay's avatar
James Dumay committed
175
- (instancetype)initWithOptions:(NSArray *)options;
176 177 178 179 180 181
/**
 * 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
 */
182
- (instancetype)initWithLibVLCInstance:(void *)playerInstance andLibrary:(VLCLibrary *)library;
183 184 185 186

/* Video View Options */
// TODO: Should be it's own object?

187 188 189
#pragma mark -
#pragma mark video functionality

Pierre's avatar
Pierre committed
190
#if !TARGET_OS_IPHONE
191 192 193 194 195
/**
 * set a video view for rendering
 * \param aVideoView instance of VLCVideoView
 * \note This setter is macOS only
 */
196
- (void)setVideoView:(VLCVideoView *)aVideoView;
197 198 199 200 201
/**
 * set a video layer for rendering
 * \param aVideoLayer instance of VLCVideoLayer
 * \note This setter is macOS only
 */
202
- (void)setVideoLayer:(VLCVideoLayer *)aVideoLayer;
Pierre's avatar
Pierre committed
203
#endif
204

205 206 207 208
/**
 * set/retrieve a video view for rendering
 * This can be any UIView or NSView or instances of VLCVideoView / VLCVideoLayer if running on macOS
 */
209
@property (strong) id drawable; /* The videoView or videoLayer */
210

211 212 213
/**
 * Set/Get current video aspect ratio.
 *
214
 * param: psz_aspect new video aspect-ratio or NULL to reset to default
215 216 217 218
 * \note Invalid aspect ratios are ignored.
 * \return the video aspect ratio or NULL if unspecified
 * (the result must be released with free()).
 */
James Dumay's avatar
James Dumay committed
219
@property (NS_NONATOMIC_IOSONLY) char *videoAspectRatio;
220

221 222 223
/**
 * Set/Get current crop filter geometry.
 *
224
 * param: psz_geometry new crop filter geometry (NULL to unset)
225 226
 * \return the crop filter geometry or NULL if unset
 */
James Dumay's avatar
James Dumay committed
227
@property (NS_NONATOMIC_IOSONLY) char *videoCropGeometry;
228

229 230 231 232 233 234 235
/**
 * Set/Get the current video scaling factor.
 * That is the ratio of the number of pixels on
 * screen to the number of pixels in the original decoded video in each
 * dimension. Zero is a special value; it will adjust the video to the output
 * window/drawable (in windowed mode) or the entire screen.
 *
236
 * param: relative scale factor as float
237
 */
238
@property (nonatomic) float scaleFactor;
239

240 241 242 243 244 245 246 247 248 249
/**
 * Take a snapshot of the current video.
 *
 * If width AND height is 0, original size is used.
 * If width OR height is 0, original aspect-ratio is preserved.
 *
 * \param path the path where to save the screenshot to
 * \param width the snapshot's width
 * \param height the snapshot's height
 */
250
- (void)saveVideoSnapshotAt:(NSString *)path withWidth:(int)width andHeight:(int)height;
251 252 253 254

/**
 * Enable or disable deinterlace filter
 *
255
 * \param name of deinterlace filter to use (availability depends on underlying VLC version), NULL to disable.
256
 */
257
- (void)setDeinterlaceFilter: (NSString *)name;
258

259 260 261
/**
 * Enable or disable deinterlace and specify which filter to use
 *
262
 * \param deinterlace mode for deinterlacing: enable, disable or auto
263 264 265 266
 * \param name of deinterlace filter to use (availability depends on underlying VLC version).
 */
- (void)setDeinterlace:(VLCDeinterlace)deinterlace withFilter:(NSString *)name;

267 268 269
/**
 * Enable or disable adjust video filter (contrast, brightness, hue, saturation, gamma)
 *
270
 * \return bool value
271
 */
272
@property (nonatomic) BOOL adjustFilterEnabled;
273 274 275
/**
 * Set/Get the adjust filter's contrast value
 *
276
 * \return float value (range: 0-2, default: 1.0)
277
 */
278
@property (nonatomic) float contrast;
279 280 281
/**
 * Set/Get the adjust filter's brightness value
 *
282
 * \return float value (range: 0-2, default: 1.0)
283
 */
284
@property (nonatomic) float brightness;
285 286 287
/**
 * Set/Get the adjust filter's hue value
 *
288
 * \return float value (range: -180-180, default: 0.)
289
 */
290
@property (nonatomic) float hue;
291 292 293
/**
 * Set/Get the adjust filter's saturation value
 *
294
 * \return float value (range: 0-3, default: 1.0)
295
 */
296
@property (nonatomic) float saturation;
297 298 299
/**
 * Set/Get the adjust filter's gamma value
 *
300
 * \return float value (range: 0-10, default: 1.0)
301
 */
302
@property (nonatomic) float gamma;
303

304 305 306 307 308 309 310 311
/**
 * Get the requested movie play rate.
 * @warning Depending on the underlying media, the requested rate may be
 * different from the real playback rate. Due to limitations of some protocols
 * this option may not be taken into account at all, if set.
 *
 * \return movie play rate
 */
312
@property (nonatomic) float rate;
313

314 315 316 317
/**
 * an audio controller object
 * \return instance of VLCAudio
 */
318
@property (nonatomic, readonly, weak) VLCAudio * audio;
319

320
/* Video Information */
321 322 323 324
/**
 * Get the current video size
 * \return video size as CGSize
 */
James Dumay's avatar
James Dumay committed
325
@property (NS_NONATOMIC_IOSONLY, readonly) CGSize videoSize;
326

327 328 329 330 331 332
/**
 * Does the current media have a video output?
 * \note a false return value doesn't mean that the video doesn't have any video
 * \note tracks. Those might just be disabled.
 * \return current video output status
 */
James Dumay's avatar
James Dumay committed
333
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL hasVideoOut;
334

335 336
/**
 * Frames per second
337
 * \deprecated provided for API compatibility only, to retrieve a media's FPS, use VLCMediaTracksInformationFrameRate.
338
 * \returns 0
339
 */
340
@property (NS_NONATOMIC_IOSONLY, readonly) float framesPerSecond __attribute__((deprecated));
341

342 343 344
#pragma mark -
#pragma mark time

345 346 347 348 349
/**
 * Sets the current position (or time) of the feed.
 * \param value New time to set the current position to.  If time is [VLCTime nullTime], 0 is assumed.
 */

350
/**
351
 * Returns the current position (or time) of the feed.
352
 * \return VLCTime object with current time.
353
 */
James Dumay's avatar
James Dumay committed
354
@property (NS_NONATOMIC_IOSONLY, strong) VLCTime *time;
355

356 357 358 359 360
/**
 * 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
 */
361
@property (nonatomic, readonly, weak) VLCTime *remainingTime;
362

363 364 365
#pragma mark -
#pragma mark ES track handling

366 367
/**
 * Return the current video track index
368
 *
369
 * \return current video track index, -1 if none or no media track
370
 *
371
 * Pass -1 to disable.
372
 */
373
@property (readwrite) int currentVideoTrackIndex;
374

375 376 377 378
/**
 * Returns the video track names, usually a language name or a description
 * It includes the "Disabled" fake track at index 0.
 */
James Dumay's avatar
James Dumay committed
379
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *videoTrackNames;
380 381 382 383 384

/**
 * Returns the video track IDs
 * those are needed to set the video index
 */
James Dumay's avatar
James Dumay committed
385
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *videoTrackIndexes;
386

387 388 389 390 391 392
/**
 * returns the number of video tracks available in the current media
 * \return number of tracks
 */
@property (NS_NONATOMIC_IOSONLY, readonly) int numberOfVideoTracks;

393
/**
394
 * Return the current video subtitle index
395
 *
396
 * \return current video subtitle index, -1 if none
397
 *
398
 * Pass -1 to disable.
399
 */
400
@property (readwrite) int currentVideoSubTitleIndex;
401

402 403 404 405
/**
 * Returns the video subtitle track names, usually a language name or a description
 * It includes the "Disabled" fake track at index 0.
 */
James Dumay's avatar
James Dumay committed
406
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *videoSubTitlesNames;
407 408 409 410 411

/**
 * Returns the video subtitle track IDs
 * those are needed to set the video subtitle index
 */
James Dumay's avatar
James Dumay committed
412
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *videoSubTitlesIndexes;
413

414 415 416 417 418 419
/**
 * returns the number of SPU tracks available in the current media
 * \return number of tracks
 */
@property (NS_NONATOMIC_IOSONLY, readonly) int numberOfSubtitlesTracks;

420 421
/**
 * Load and set a specific video subtitle, from a file.
422
 *
423
 * \deprecated use addPlaybackSlave:type:enforce: instead
424
 */
425
- (BOOL)openVideoSubTitlesFromFile:(NSString *)path __attribute__((deprecated));
426

427 428 429 430 431 432 433 434 435 436 437 438 439
/**
 * VLCMediaPlaybackNavigationAction describes actions which can be performed to navigate an interactive title
 */
typedef NS_ENUM(unsigned, VLCMediaPlaybackSlaveType)
{
    VLCMediaPlaybackSlaveTypeSubtitle = 0,
    VLCMediaPlaybackSlaveTypeAudio
};

/**
 * Add additional input sources to a playing media item
 * This way, you can add subtitles or audio files to an existing input stream
 * For the user, it will appear as if they were part of the existing stream
440 441 442
 * \param slaveURL of the content to be added
 * \param slaveType content type
 * \param enforceSelection switch to the added accessory content
443 444 445
 */
- (int)addPlaybackSlave:(NSURL *)slaveURL type:(VLCMediaPlaybackSlaveType)slaveType enforce:(BOOL)enforceSelection;

446 447 448 449 450 451 452 453
/**
 * Get the current subtitle delay. Positive values means subtitles are being
 * displayed later, negative values earlier.
 *
 * \return time (in microseconds) the display of subtitles is being delayed
 */
@property (readwrite) NSInteger currentVideoSubTitleDelay;

454 455 456 457 458 459
/**
 * Chapter selection and enumeration, it is bound
 * to a title option.
 */

/**
460 461
 * Return the current chapter index
 * \return current chapter index or -1 if there is no chapter
462
 */
463
@property (readwrite) int currentChapterIndex;
464 465 466
/**
 * switch to the previous chapter
 */
467
- (void)previousChapter;
468 469 470
/**
 * switch to the next chapter
 */
471
- (void)nextChapter;
472 473 474 475
/**
 * returns the number of chapters for a given title
 * \param titleIndex the index of the title you are requesting the chapters for
 */
476
- (int)numberOfChaptersForTitle:(int)titleIndex;
477 478 479 480 481

/**
 * Chapters of a given title index
 * \deprecated Use chapterDescriptionsOfTitle instead
 */
482 483
- (NSArray *)chaptersForTitleIndex:(int)titleIndex __attribute__((deprecated));

484 485 486
/**
 * dictionary value for the user-facing chapter name
 */
487
extern NSString *const VLCChapterDescriptionName;
488 489 490
/**
 * dictionary value for the chapter's time offset
 */
491
extern NSString *const VLCChapterDescriptionTimeOffset;
492 493 494
/**
 * dictionary value for the chapter's duration
 */
495 496 497 498 499 500 501 502
extern NSString *const VLCChapterDescriptionDuration;

/**
 * chapter descriptions
 * an array of all chapters of the given title including information about
 * 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
503 504 505
 * \see VLCChapterDescriptionName
 * \see VLCChapterDescriptionTimeOffset
 * \see VLCChapterDescriptionDuration
506 507
 */
- (NSArray *)chapterDescriptionsOfTitle:(int)titleIndex;
508 509

/**
510 511
 * Return the current title index
 * \return title index currently playing, or -1 if none
512
 */
513
@property (readwrite) int currentTitleIndex;
514 515 516 517
/**
 * number of titles available for the current media
 * \return the number of titles
 */
518
@property (readonly) int numberOfTitles;
519 520 521 522 523

/**
 * count of titles
 * \deprecated Use numberOfTitles instead
 */
524
@property (readonly) NSUInteger countOfTitles __attribute__((deprecated));
525 526 527 528
/**
 * array of available titles
 * \deprecated Use titleDescriptions instead
 */
529 530
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titles __attribute__((deprecated));

531 532 533
/**
 * dictionary value for the user-facing title name
 */
534
extern NSString *const VLCTitleDescriptionName;
535 536 537
/**
 * dictionary value for the title's duration
 */
538
extern NSString *const VLCTitleDescriptionDuration;
539 540 541
/**
 * dictionary value whether the title is a menu or not
 */
542 543 544 545 546 547 548
extern NSString *const VLCTitleDescriptionIsMenu;

/**
 * title descriptions
 * 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
549 550 551
 * \see VLCTitleDescriptionName
 * \see VLCTitleDescriptionDuration
 * \see VLCTitleDescriptionIsMenu
552 553 554 555 556 557 558 559
 */
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *titleDescriptions;

/**
 * the title with the longest duration
 * \return int matching the title index
 */
@property (readonly) int indexOfLongestTitle;
560

561
/* Audio Options */
562 563 564

/**
 * Return the current audio track index
565
 *
566
 * \return current audio track index, -1 if none or no media track
567
 *
568
 * Pass -1 to disable.
569
 */
570
@property (readwrite) int currentAudioTrackIndex;
571

572 573 574 575
/**
 * Returns the audio track names, usually a language name or a description
 * It includes the "Disabled" fake track at index 0.
 */
James Dumay's avatar
James Dumay committed
576
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *audioTrackNames;
577 578 579 580 581

/**
 * Returns the audio track IDs
 * those are needed to set the video index
 */
James Dumay's avatar
James Dumay committed
582
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *audioTrackIndexes;
583

584 585 586 587 588 589
/**
 * returns the number of audio tracks available in the current media
 * \return number of tracks
 */
@property (NS_NONATOMIC_IOSONLY, readonly) int numberOfAudioTracks;

590 591 592
#pragma mark -
#pragma mark audio functionality

593 594 595 596
/**
 * sets / returns the current audio channel
 * \return the currently set audio channel
 */
James Dumay's avatar
James Dumay committed
597
@property (NS_NONATOMIC_IOSONLY) int audioChannel;
598

599 600 601 602 603 604 605 606
/**
 * Get the current audio delay. Positive values means audio is delayed further,
 * negative values less.
 *
 * \return time (in microseconds) the audio playback is being delayed
 */
@property (readwrite) NSInteger currentAudioPlaybackDelay;

607
#pragma mark -
608 609 610 611
#pragma mark equalizer

/**
 * Get a list of available equalizer profiles
612
 * \note Current versions do not allow the addition of further profiles
613 614 615 616
 *       so you need to handle this in your app.
 *
 * \return array of equalizer profiles
 */
617
@property (weak, readonly) NSArray *equalizerProfiles;
618 619 620

/**
 * Re-set the equalizer to a profile retrieved from the list
621
 * \note This doesn't enable the Equalizer automagically
622 623 624 625 626
 */
- (void)resetEqualizerFromProfile:(unsigned)profile;

/**
 * Toggle equalizer state
627
 * param: bool value to enable/disable the equalizer
628
 * \note this can fail, if failed the value will not be changed
629 630 631 632 633
 * \return current state */
@property (readwrite) BOOL equalizerEnabled;

/**
 * Set amplification level
634
 * param: The supplied amplification value will be clamped to the -20.0 to +20.0 range.
635 636 637 638 639 640 641 642 643 644 645
 * \note this will create and enabled an Equalizer instance if not present
 * \return current amplification level */
@property (readwrite) CGFloat preAmplification;

/**
 * Number of equalizer bands
 * \return the number of equalizer bands available in the current release */
@property (readonly) unsigned numberOfBands;

/**
 * frequency of equalizer band
646
 * \param index the band index
647 648 649 650 651 652 653 654 655 656 657 658 659 660 661 662
 * \return frequency of the requested equalizer band */
- (CGFloat)frequencyOfBandAtIndex:(unsigned)index;

/**
 * set amplification for band
 * \param amplification value (clamped to the -20.0 to +20.0 range)
 * \param index of the respective band */
- (void)setAmplification:(CGFloat)amplification forBand:(unsigned)index;

/**
 * amplification of band
 * \param index of the band
 * \return current amplification value (clamped to the -20.0 to +20.0 range) */
- (CGFloat)amplificationOfBand:(unsigned)index;

#pragma mark -
663 664
#pragma mark media handling

665
/* Media Options */
666 667 668
/**
 * The currently media instance set to play
 */
James Dumay's avatar
James Dumay committed
669
@property (NS_NONATOMIC_IOSONLY, strong) VLCMedia *media;
670

671 672
#pragma mark -
#pragma mark playback operations
673
/**
674
 * Plays a media resource using the currently selected media controller (or
675
 * default controller. If feed was paused then the feed resumes at the position
676 677
 * it was paused in.
 */
678
- (void)play;
679 680

/**
681
 * Set the pause state of the feed. Do nothing if already paused.
682 683 684
 */
- (void)pause;

685 686 687 688 689
/**
 * Stop the playing.
 */
- (void)stop;

690 691 692 693 694
/**
 * Advance one frame.
 */
- (void)gotoNextFrame;

695 696 697
/**
 * Fast forwards through the feed at the standard 1x rate.
 */
698
- (void)fastForward;
699 700 701 702 703

/**
 * Fast forwards through the feed at the rate specified.
 * \param rate Rate at which the feed should be fast forwarded.
 */
704
- (void)fastForwardAtRate:(float)rate;
705 706 707 708

/**
 * Rewinds through the feed at the standard 1x rate.
 */
709
- (void)rewind;
710 711 712 713 714

/**
 * Rewinds through the feed at the rate specified.
 * \param rate Rate at which the feed should be fast rewound.
 */
715
- (void)rewindAtRate:(float)rate;
716

717 718 719 720
/**
 * Jumps shortly backward in current stream if seeking is supported.
 * \param interval to skip, in sec.
 */
721
- (void)jumpBackward:(int)interval;
722 723 724 725 726

/**
 * Jumps shortly forward in current stream if seeking is supported.
 * \param interval to skip, in sec.
 */
727
- (void)jumpForward:(int)interval;
728 729 730 731 732 733 734 735 736 737 738 739 740 741 742 743 744 745 746 747 748 749 750 751 752 753 754 755 756 757 758 759 760 761 762 763 764 765 766 767 768

/**
 * Jumps shortly backward in current stream if seeking is supported.
 */
- (void)extraShortJumpBackward;

/**
 * Jumps shortly forward in current stream if seeking is supported.
 */
- (void)extraShortJumpForward;

/**
 * Jumps shortly backward in current stream if seeking is supported.
 */
- (void)shortJumpBackward;

/**
 * Jumps shortly forward in current stream if seeking is supported.
 */
- (void)shortJumpForward;

/**
 * Jumps shortly backward in current stream if seeking is supported.
 */
- (void)mediumJumpBackward;

/**
 * Jumps shortly forward in current stream if seeking is supported.
 */
- (void)mediumJumpForward;

/**
 * Jumps shortly backward in current stream if seeking is supported.
 */
- (void)longJumpBackward;

/**
 * Jumps shortly forward in current stream if seeking is supported.
 */
- (void)longJumpForward;

769 770 771 772 773
/**
 * performs navigation actions on interactive titles
 */
- (void)performNavigationAction:(VLCMediaPlaybackNavigationAction)action;

774 775
/**
 * Updates viewpoint with given values.
776 777 778 779
 * \param view point yaw in degrees  ]-180;180]
 * \param view point pitch in degrees  ]-90;90]
 * \param view point roll in degrees ]-180;180]
 * \param field of view in degrees ]0;180[ (default 80.)
780 781
 * \param absolute if true replace the old viewpoint with the new one. If
 * false, increase/decrease it.
782
 * \return NO in case of error, YES otherwise
783 784
 * \note This will create a viewpoint instance if not present.
 */
785 786 787 788 789 790 791 792 793 794 795 796 797 798 799 800 801 802 803 804 805 806 807 808 809 810 811 812 813
- (BOOL)updateViewpoint:(float)yaw pitch:(float)pitch roll:(float)roll fov:(float)fov absolute:(BOOL)absolute;

/**
* Get the view point yaw in degrees
*
* \return view point yaw in degrees  ]-180;180]
*/
@property (nonatomic) float yaw;

/**
 * Get the view point pitch in degrees
 *
 * \return view point pitch in degrees  ]-90;90]
 */
@property (nonatomic) float pitch;

/**
 * Get the view point roll in degrees
 *
 * \return view point roll in degrees ]-180;180]
 */
@property (nonatomic) float roll;

/**
 * Set/Get the adjust filter's gamma value
 *
 * \return field of view in degrees ]0;180[ (default 80.)
 */
@property (nonatomic) float fov;
814

815 816
#pragma mark -
#pragma mark playback information
817 818 819 820
/**
 * Playback state flag identifying that the stream is currently playing.
 * \return TRUE if the feed is playing, FALSE if otherwise.
 */
James Dumay's avatar
James Dumay committed
821
@property (NS_NONATOMIC_IOSONLY, getter=isPlaying, readonly) BOOL playing;
822 823 824 825 826

/**
 * Playback state flag identifying wheather the stream will play.
 * \return TRUE if the feed is ready for playback, FALSE if otherwise.
 */
James Dumay's avatar
James Dumay committed
827
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL willPlay;
828 829 830 831 832

/**
 * Playback's current state.
 * \see VLCMediaState
 */
James Dumay's avatar
James Dumay committed
833
@property (NS_NONATOMIC_IOSONLY, readonly) VLCMediaPlayerState state;
834 835

/**
836
 * Returns the receiver's position in the reading.
837
 * \return movie position as percentage between 0.0 and 1.0.
838
 */
James Dumay's avatar
James Dumay committed
839
@property (NS_NONATOMIC_IOSONLY) float position;
840

841 842
/**
 * Set movie position. This has no effect if playback is not enabled.
843
 * \note movie position as percentage between 0.0 and 1.0.
844
 */
James Dumay's avatar
James Dumay committed
845
@property (NS_NONATOMIC_IOSONLY, getter=isSeekable, readonly) BOOL seekable;
846

847 848 849 850
/**
 * property whether the currently playing media can be paused (or not)
 * \return BOOL value
 */
James Dumay's avatar
James Dumay committed
851
@property (NS_NONATOMIC_IOSONLY, readonly) BOOL canPause;
852

853 854
/**
 * Array of taken snapshots of the current video output
855
 * \return a NSArray of NSString instances containing the names
856 857
 * \note This property is not available to macOS
 */
858 859
@property (NS_NONATOMIC_IOSONLY, readonly, copy) NSArray *snapshots;

860
#if TARGET_OS_IPHONE
861 862 863 864
/**
 * Get last snapshot available.
 * \return an UIImage with the last snapshot available.
 * \note return value is nil if there is no snapshot
865
 * \note This property is not available to macOS
866 867
 */
@property (NS_NONATOMIC_IOSONLY, readonly) UIImage *lastSnapshot;
868 869 870 871 872 873 874 875
#else
/**
 * Get last snapshot available.
 * \return an NSImage with the last snapshot available.
 * \note return value is nil if there is no snapshot
 * \note This property is not available to iOS and tvOS
 */
@property (NS_NONATOMIC_IOSONLY, readonly) NSImage *lastSnapshot;
876 877
#endif

Soomin Lee's avatar
Soomin Lee committed
878 879 880 881 882 883 884 885 886 887 888 889 890
#pragma mark -
#pragma mark Renderer

/**
 * Sets a `VLCRendererItem` to the current media player
 * \param item `VLCRendererItem` discovered by `VLCRendererDiscoverer`
 * \return `YES` if successful, `NO` otherwise
 * \note Must be called before the first call of `play` to take effect
 * \see VLCRendererDiscoverer
 * \see VLCRendererItem
 */
- (BOOL)setRendererItem:(VLCRendererItem *)item;

891
@end