Requirements
The PRESTOplay SDK for Apple is delivered as XCFramework and with a CocoaPods repository that can be added to your application build. All required dependencies are either:
- Contained in the bundle repository
- Available on a public repository like CocoaPods
To work with the PRESTOplay SDK for Apple you need to use the Xcode for your application builds.
License
Create License Keys tied to your application bundle through https://downloads.castlabs.com
The license model allows activating additional plugins and changing the expiration date of the license remotely. This will help to avoid issues when the license runs out and you can not quickly re-deploy your Application.
In our download portal you go to the license you need and select Manage keys:
As you do not have any keys associated with the license, you will be shown this message:
Please select Create a key. After this you are taken to this screen:
Project Setup
Unzip the installation bundle
Add
PRESTOplay.xcframework
file to your project “Frameworks, Libraries, and Embedded Content”. Choose “Embed & Sign” as the “Embed Option”(Optional) Repeat step (2) for any additional plugin frameworks
Initialization
Pass the license string and the list of plugins you want to activate to the register()
method
import PRESTOplay
import CastlabsApple
import CastlabsVT
PRESTOplaySDK.shared.register("LICENSE", [HLSPlugin(), VTPlugin()])
It’s your apps responsibility to set the correct category for AVAudioSession
. If your app does only playback AVAudioSessionCategory.playback
is sufficient, if your app does playback and record you would need AVAudioSessionCategory.playAndRecord
. You only need to do it once per app lifetime.
let audioSession = AVAudioSession.sharedInstance()
do {
try audioSession.setCategory(.playback)
try audioSession.setActive(true, options: .notifyOthersOnDeactivation)
} catch {
log_e("Cannot initialize audio session")
}
Error Handling
Because all player preparations and most of the playback operations occur asynchronously, errors are reported through the PRESTOplaySDK.shared.onError
block and you are encouraged to attach your handler before opening any content. Opening content might already raise an issue, for example if the Manifest URL does not provide data, and these issues will only be reported through the onError
callback.
PRESTOplaySDK.shared.onError = { component, error in
if error.type == .player_avplayer_error &&
error.severity == .warning {
// filtered error
}
}
Fatal errors are also reported in the PlayerAPI
onState
block as they impact the overall session state.
SDK assumptions
- Minimal supported iOS/iPadOS/tvOS version is set to 13.
- Frameworks in SDK are built as dynamic frameworks.
Supported platforms
iOS/iPadOS and tvOS: Unified iOS, iPadOS, and tvOS SDK enable comprehensive support for each platform, ensuring seamless API interoperability and feature compatibility.
Mac: The SDK provides support for Macs with Apple Silicon.
Test Projects
Included in the main package examples/
directory.
examples
Simple demo examples that test the building of core features and plugin integrations. They are meant to work without any user interaction and with a very simple UI.
Examples are built with UIKit.
examples/Demos
More complicated demo (all-in-one app) with specialized examples and use-cases. For instance: if you want to present / test WebVTT subtitles it is fine to create a
Demo
for that use-case.Demo applications are built with
SwiftUI
.
Crash Reports
If a crash occurs when using our release builds, you will see that part of the stack trace is obfuscated due to security reasons. However there’s still a way to re-symbolicate the crash if you send us the load address of our libraries at crash time.
Crash dumps retrieved directly from the device
If the crash dump is retrieved directly from the device via Xcode (Window → Devices → View Device Logs), all the info we need is in the crash log itself:
Architecture: Check if ARM or ARM-64 in the Code Type line
Load address: Either check in the Binary Images, or directly from the stack line (the load address in the line “0 CastlabsDASH 0x00460b8a 0x2be000 + 1715082” is 0x2be000)
Crash dumps retrieved via Crashlytics
Crashlytics doesn’t let you know the load address of the binaries, but it still reports the actual address in memory of a symbol, not the offset from the load address, in its stack traces. You need to attach information about the load addresses to the crash dump via Crashlytics Key-Value system.
Get load addresses and pass them to Crashlytics
var index: UInt32 = 0
while index < _dyld_image_count() {
let header = _dyld_get_image_header(index)
if let name = String(validatingUTF8: _dyld_get_image_name(index)), name.contains("Castlabs") {
header.debugDescription
break
}
index += 1
}
Retrieve them from Crashlytics web UI: select a crash then choose “View All Sessions”. Download the stack trace and text file and copy the pseudo-json with the load addresses for the “CASTLABS LOAD ADDRESSES” key in the “Keys” section.
The Crashlytics stack trace does not specify the CPU architecture, but it contains the device type so you can match it up by looking at the device specs.
CocoaPods
Our SDK can be included and set up via CocoaPods.
The list of supported plugins for each platform can be faound in the SDK bundle: configs/
(for instance: configs/release-ios-plugins
, configs/release-tvos-plugins
, configs/release-catalyst-plugins
).
Access to Cocoapods is public for v4
.
Please check examples
to see pods integrations.
CocoaPods version required is >= 1.10.0. The SDK consists of Dynamic Frameworks.