Migrate to v1.1

When updating the SDK from version 1.0.z to 1.1.z you will need to make some changes to your code. This document explains the changes required to build your application again with the new SDK version.

Package name changes

The SDK switched to Kotlin Multiplatform starting from v1.1. As a side effect some of our modules have been moved around or renamed.

Each module now has separate builds for different platforms (common, jvm and android). Additionally the separate jellyfin-platform-android module was merged into jellyfin-core.

The table below shows the new names to be used:

Module (before)	Module (after)
jellyfin-core	jellyfin-core
jellyfin-platform-android	jellyfin-core
jellyfin-api	jellyfin-api
jellyfin-model	jellyfin-model

Gradle will automatically use the Android build when the Android plugin is enabled. If you need to explicitly use the Android build you can add the "-android" suffix.

SDK initialization

The Jellyfin {} function to create an instance of the SDK was renamed to createJellyfin {}. The options set inside of this builder changed depending on your platform. If the settings are incorrect it will throw an exception on initialization.

JVM

On the JVM there aren't many changes. Just make sure to rename Jellyfin to createJellyfin.

createJellyfin {
	clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7")
}

Android

No longer needs the android() function called as this is automatically applied. Instead, set the context variable to an Android context.

createJellyfin {
	context = /* Android Context */
	clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7")
}

API extensions

API interaction was improved for better performance and to make it easier to use. Previously when using the API you had to follow two steps:

1. Create API client instance using jellyfin.createApi
2. Create instance of an API class that contains operations, like UserApi.

This came with a few issues. First, you had to keep track of those API classes to avoid constantly creating new ones. Secondly, you couldn't use autocomplete in an IDE to easily find the available API classes and had to rely on api.jellyfin.org.

The old behavior still exists in v1.1, and the new behavior actually relies on it. You can now use extension properties to get an API instance stored in the API client. A short example follows:

val api = jellyfin.createApi(/* ... */)

// Old
val userApi = UserApi(api)

// New
val userApi = api.userApi

The extension properties should be imported, an IDE will do this automatically. The API class is initialized on first use and stored in the API client.

Collections in the API

Previously when using collections in the parameters or request bodies of operations you had to use an instance of List. Starting from v1.1 the types have changed to Collection. This means you can use a Set or any other type that implements Collection.

Error reporting in RecommendedServerDiscovery

The RecommendedServerDiscovery class (jellyfin.discovery.getRecommendedServers(candidates)) is a powerful tool to correct user inputted server addresses and find a SDK compatible server. One issue we've observed in the Jellyfin Android apps was that it lacked information as to why a server was not recommended if the input is correct. To fix this a part of the algorithm was rewritten to report issues. If you're using this function you can now use the newly added issues collection added to the returned RecommendedServerInfo. We currently have the following issues:

• MissingSystemInfo(throwable: Throwable?)

  No system information found. This could happen due too networking issues or an invalid server address.

• InvalidProductName(productName: String?)

  The product name in the system information is incorrect.

• MissingVersion

  No version found in system information.

• UnsupportedServerVersion(public val version: ServerVersion)

  The SDK does not support the server version.

• OutdatedServerVersion(version: ServerVersion)

  The SDK uses a newer version of the API compared to the server. While this normally shouldn't be a problem, it may potentially cause problems like crashes.

• SlowResponse(responseTime: Long)

  The system information response was slow.

Replacing KtorClient

This version of the SDK changed how the backend of the API part works. Previously the createApi function would return a KtorClient instance and you might have used this type in your code. Starting from v1.1 it is strongly advised to instead use the ApiClient interface type.

The SDK now supports different ApiClient implementations. An ApiClient is used to handle the HTTP part while serializing and creating models is done by the SDK. We might replace KtorClient in the future or add different implementations.