Cheat Sheet

Feel free to copy & paste code below.

This documentation will describe some common usage of SwiftyPlayer.

Initialization

Use Player for audio playback, use VideoPlayer for video playback

let player = Player()

let player = VideoPlayer()

VideoPlayer is a subclass of Player, VideoPlayer will monitor when the application enters the foreground and exits from the background. Support background video playback, just use isBackgroundPlaybackSupported.

In addition, VideoPlayer also provides videoGravity to set the video's stretching mode. The attribute value is mapped with AVLayerVideoGravity, and the naming and function are consistent.

extension VideoPlayerGravity {
    /// Preserve aspect ratio; fit within layer bounds.
    public static let resizeAspect = VideoPlayerGravity(rawValue: AVLayerVideoGravity.resizeAspect.rawValue)

    /// Preserve aspect ratio; fill layer bounds.
    public static let resizeAspectFill = VideoPlayerGravity(rawValue: AVLayerVideoGravity.resizeAspectFill.rawValue)

    /// Stretch to fill layer bounds.
    public static let resize = VideoPlayerGravity(rawValue: AVLayerVideoGravity.resize.rawValue)
}

Playback with a URL

let url = URL(string: "https://example.com/audio.mp3")!
if let playable = PlayableItem(itemResources: [.medium: url]) {
    player.play(item: playable)
}

When the PlayableItem is initialized, the parameter needs to be passed in a dictionary, [PlayableQuality: ResourceConvertible]. PlayableQuality provides three types:

extension PlayableQuality {

    public static let low = PlayableQuality(rawValue: 0)

    public static let medium = PlayableQuality(rawValue: 500)

    public static let high = PlayableQuality(rawValue: 999)

}

You can customize the resource quality like using UILayoutPriority, just use:

let newValue: UInt = 777
let newQuality = PlayableQuality(rawValue: newValue)

PlayerDelegate

SwiftyPlayer uses PlayerDelegate to callback player events, the following delegate methods are defined in PlayerDelegate.

1. This method gets called when the player changes its state.

func player(_ player: Player, didChangeStateFrom from: PlayerState, to state: PlayerState)

PlayerState defines the following player state:

public enum PlayerState {
    case buffering
    case playing
    case paused
    case stopped
    case waitingForConnection
    case failed(PlayerError)
}

2. This method gets called when the player is about to start playing a new item.

func player(_ player: Player, willStartPlaying item: PlayableItem)

3. This method gets called when an error occurred during AudioSession setup.

func player(_ player: Player, setAudioSessionErrorOccured error: Error?)

4. This method gets called a regular time interval while playing.

func player(_ player: Player, didUpdateProgressionTo time: TimeInterval, percentageRead: Float)

5. This method gets called when the current item duration has been found.

func player(_ player: Player, didFindDuration duration: TimeInterval, for item: PlayableItem)

6. This methods gets called before duration gets updated with discovered metadata.

func player(_ player: Player, didUpdateEmptyMetadataOn item: PlayableItem, withData data: Metadata)

7. This method gets called while the player is loading the file

func player(_ player: Player, didLoad range: TimeRange, for item: PlayableItem)

8. This methods gets called when the resource playback ends.

func player(_ player: Player, didEndedPlaying item: PlayableItem)

PlayerAudioSession

PlayerAudioSession is used to set AVAudioSession.Category. Player provides setCategory(_:, mode:, options:, notifyOtherOnDeactivation:), this method does not take effect immediately, but is set before the resource is played.

public func setCategory(
    _ category: PlayerAudioSession.Category,
    mode: PlayerAudioSession.Mode = .default,
    options: PlayerAudioSession.CategoryOptions = [],
    notifyOthersOnDeactivation: Bool = true
)

PlayerAudioSession.Category/PlayerAudioSession.Mode/PlayerAudioSession.CategoryOptions are mapped to the attribute of the same name of AVAudioSession.

MPRemoteCommandCenter

Player implements playCommand/pauseCommand/previousTrackCommand/nextTrackCommand/stopCommand/changePlaybackPositionCommand by default. If you don's need these default implementations, you turn oof unnecessary commands by setting the Player's remoteCommandOptions property.

/// For example, if you just need two commands like playCommand and pauseCommand 
player.remoteCommandOptions = [
    .play,
    .pause,
]

Loop mode

You can modify the player's var mode: Player.Mode property to set the player's loop mode. Player.Mode has four types, .normal/.shuffle/.repeat/.repeatAll.

After a video/audio ends, actionAtItemEnd property will indicate whether to automatically play the next one or just be paused.