# Introduction

## player-sdk-swift

This audio player SDK is written in Swift 4 and runs on iPhones and iPads from iOS 9 to now.

An example app using this player SDK can be run from the XCode-Project in the repository [app-example-ios](https://github.com/ybrid/app-example-ios).

### Why yet another player?

This audio player SDK offers low latency live and on-demand streaming with a high stability. All current features see below:

| Specifications                                                                                  |                                                                                                                                                                                                                          |
| ----------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Audio Formats                                                                                   | MP3, AAC, Ogg/Opus                                                                                                                                                                                                       |
| Streaming Compatibility                                                                         | Icecast, ICY, Ybrid, HTTP, HTTPS, File                                                                                                                                                                                   |
| Player features                                                                                 | Play, Stop, Pause                                                                                                                                                                                                        |
| [Ybrid features](https://ybrid.gitbook.io/player-sdk-swift/readme_ybrid#ybrid-features-are)     | Swap item, Swap service, max bit-rate                                                                                                                                                                                    |
| [Timeshift features](https://ybrid.gitbook.io/player-sdk-swift/readme_ybrid#ybrid-features-are) | <p>Wind back, wind forward, wind to live, wind to date, skip back (to item type), skip forward (to item type)</p><p><em>ItemTypes: News, Music, Voice, Weather, Traffic, Jingle, Advertisement, Comedy, Unknown</em></p> |
| Metadata                                                                                        | ICY (MP3, AAC), VorbisComments (Opus Tags), Ybrid (e.g. current, next)                                                                                                                                                   |
| OS-compatibility                                                                                | iOS 9 - now                                                                                                                                                                                                              |
| Runtime / language requirement                                                                  | ≥ Swift 4                                                                                                                                                                                                                |
| Loggin                                                                                          | Unified Logging System                                                                                                                                                                                                   |
| SDK Integration                                                                                 | [Swift Package Manager](#integration), [CocoaPods](#integration)                                                                                                                                                         |
| Device storage limit                                                                            | 128 MB (adjustable)                                                                                                                                                                                                      |
| Flow control & playback                                                                         | Buffer status reporting, Automatic handling of network problems                                                                                                                                                          |
| Monetization                                                                                    | ≥ VAST 3.0                                                                                                                                                                                                               |

### How to use

After [integrating](https://github.com/ybrid/player-sdk-swift#integration) the framework into your project, use the following lines of Swift code to listen to your radio:

```swift
import YbridPlayerSDK

let myEndpoint = MediaEndpoint(mediaUri: "https://democast.ybrid.io/adaptive-demo")
try AudioPlayer.open(for: myEndpoint, listener: nil) {
    (control) in /// called asychronously

    control.play()
    sleep(10) /// listen to audio

    control.stop()
    /// ...
    control.close()
}
sleep(10) /// of course the program must not end here
```

AudioPlayer.open first detects the transmission protocol and encoding of the audio content and [metadata](https://ybrid.gitbook.io/player-sdk-swift/readme_metadata) and then returns a playback control asynchronously. A media-specific control can be taken from the full `open` method, [see README\_Ybrid](https://ybrid.gitbook.io/player-sdk-swift/readme_ybrid).

Possible playback states of the player are

```swift
public enum PlaybackState {
    case buffering 
    case playing 
    case stopped 
    case pausing 
}
```

With mediaUri addressing an on-demand file, you can safely use `control.pause()` if `control.canPause` is true.

As a developer, you probably want to receive changes of the playback state. Implement AudioPlayerListener and pass it via the listener parameter above. You will also receive changes of metadata, hints on problems like network stalls as well as relevant durations and playback buffer size.

```swift
public protocol AudioPlayerListener : class {
    func stateChanged(_ state: PlaybackState)
    func metadataChanged(_ metadata: Metadata)
    func error(_ severity:ErrorSeverity, _ exception: AudioPlayerError)
    func playingSince(_ seconds: TimeInterval?)
    func durationReadyToPlay(_ seconds: TimeInterval?)
    func durationConnected(_ seconds: TimeInterval?)
    func bufferSize(averagedSeconds: TimeInterval?, currentSeconds: TimeInterval?)
}
```

In case of network stalls, the state will change from playing to buffering at the time of exhausting audio buffer. Try it out! After reconnecting to a network, the player will resume.

Errors are raised when occurring. Your handling may use the message, the `code`, or just `ErrorSeverity` of `AudioPlayerError`.

Further interfaces concern [product version and handling of memory issues](https://ybrid.gitbook.io/player-sdk-swift/readme_product).

### Development environment

We use XCode version 12 with swift 4 and CocoaPods 1.10. According to the nature of evolved XCFrameworks, 'player-sdk-swift.xcworkspace' should be compatible with elder versions of XCode.

To generate the release artifact 'YbridPlayerSDK.xcframework', we use a shell script written for macOS's terminal, currently version 11.2. Since it wraps xcodebuild commands, it should be easily translated to other operating systems.

### Integration

'YbridPlayerSDK.xcframework' uses 'YbridOpus.xcframework' and 'YbridOgg.xcframework'.

#### If you use Cocoapods <a href="#integration_cocoapods" id="integration_cocoapods"></a>

The Cocoa Podfile of a project using this audio player should look like

```ruby
platform :ios, '9.0'
target 'app-example-ios' do
  use_frameworks!
  source 'https://github.com/CocoaPods/Specs.git'
  pod 'YbridPlayerSDK'
end
```

#### If you use Swift Packages <a href="#integration_swiftpackagemanager" id="integration_swiftpackagemanager"></a>

A Swift Package uses YbridPlayerSDK as Swift Package with the following lines (three Packages) in Package.swift:

```swift
// swift-tools-version:5.3
  ...
  dependencies: [
    .package(
        name: "YbridOpus",
        url: "git@github.com:ybrid/opus-swift.git",
        from: "0.8.0"),
    .package(
        name: "YbridOgg",
        url: "git@github.com:ybrid/ogg-swift.git",
        from: "0.8.0"),

    .package(
        name: "YbridPlayerSDK",
        url: "git@github.com:ybrid/player-sdk-swift.git",
        from: "0.13.1"),
  ...
```

Or in a Xcode project, choose "File" -> "Swift Packages" -> "Add Package Dependency" three times and pass url, version and name above. Have a look at the properties editor, and ensure the Packages are shown in section 'Frameworks, Libraries and Embedded Content' of the target's 'General' tab.

#### If you don't use CocoaPods or Swift Packages

If you manage packages in another way, you may manually download the necessary XCFramewoks and embed them into your project. Take the following assets from the latest release

1. YbridPlayerSDK.xcframework.zip from [this repository/releases](https://github.com/ybrid/player-sdk-swift/releases)
2. YbridOgg.xcframework.zip from [ybrid/ogg-swift/releases](https://github.com/ybrid/ogg-swift/releases)
3. YbridOpus.xcframework.zip from [ybrid/opus-swift/releases](https://github.com/ybrid/opus-swift/releases)

Unzip the files into a directory called 'Frameworks' of your XCode project. In the properties editor, drag and drop the directories into the section 'Frameworks, Libraries and Embedded Content' of the target's 'General' tab. Please report any issue to tell us your need.

### Further documentation

An excellent start to dive into technical details is [the overview](https://github.com/ybrid/overview).

For a deeper insight into the structure of metadata and the power of ybrid [see Ybrid docs](https://github.com/ybrid/player-interaction/blob/master/doc).

### Contributing

You are welcome to [contribute](https://github.com/ybrid/player-sdk-swift/blob/master/CONTRIBUTING.md) in many ways.

## Licenses

This project uses [ogg-swift](https://github.com/ybrid/ogg-swift) and [opus-swift](https://github.com/ybrid/opus-swift) which are MIT licensed. Ogg and Opus carry BSD licenses, see 3rd party section in the [LICENSE](https://github.com/ybrid/player-sdk-swift/blob/master/LICENSE/README.md) file.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://ybrid.gitbook.io/player-sdk-swift/readme.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.