Jellyfin Kotlin SDK

The Jellyfin Kotlin SDK is a library implementing the Jellyfin API to easily access servers. It is currently available for the JVM and Android 4.4 and up. Java 8 or higher is required. Android versions below Android 8 should use library desugaring.

Setup

Releases are published to mavenCentral(). Make sure to use the correct library depending on your
platform.

Latest version on Maven Central

Gradle with Kotlin DSL

implementation("org.jellyfin.sdk:jellyfin-core:$sdkVersion")

// Or when using Android
implementation("org.jellyfin.sdk:jellyfin-platform-android:$sdkVersion")
Gradle with Groovy 
implementation "org.jellyfin.sdk:jellyfin-core:$sdkVersion"

// Or when using Android
implementation "org.jellyfin.sdk:jellyfin-platform-android:$sdkVersion"
Maven 
<dependency>
    <groupId>org.jellyfin.sdk</groupId>
    <artifactId>jellyfin-core</artifactId>
    <version>$sdkVersion</version>
</dependency>

<!-- Or when using Android -->
<dependency>
    <groupId>org.jellyfin.sdk</groupId>
    <artifactId>jellyfin-platform-android</artifactId>
    <version>$sdkVersion</version>
</dependency>
Using SNAPSHOT versions

When working on new features in your application you might need a build of the SDK targetting the next server version.
For this use case we publish two SNAPSHOT releases: master-SNAPSHOT and openapi-unstable-SNAPSHOT. To use the
snaphot versions, add the snapshot repository to your build script:
https://s01.oss.sonatype.org/content/repositories/snapshots/

An example using Gradle with Kotlin DSL that only allows the master-SNAPSHOT version:

repositories {
    maven("https://s01.oss.sonatype.org/content/repositories/snapshots/") {
        content {
            // Only allow SDK snapshots
            includeVersionByRegex("org\\.jellyfin\\.sdk", ".*", "master-SNAPSHOT")
        }
    }
}

Usage

Creating a Jellyfin instance

Most functionality of the SDK requires an instance of the Jellyfin class. This class holds
the configuration required to make API calls and platform specific options. The Jellyfin class can
be instantiated using a custom Kotlin DSL:

val jellyfin = Jellyfin {
    clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7",)
    
    // Uncomment if not using jellyfin-platform-android:
    // deviceInfo = DeviceInfo(id = UUID.randomUUID().toString(), name = "Awesome device",)

    // Uncomment when using jellyfin-platform-android:
    // android()
}

Make sure to supply the client and device information if you want to make API calls. Use the
android() helper function when targeting Android to enable server discovery and set the device
information automatically.

Creating an API instance

API calls require an API instance. This can be done with the createApi function. It requires a
server address. The client and device information are set automatically but can be changed. All
properties can be changed later in the API instance.

val api = jellyfin.createApi(
    baseUrl = "https://demo.jellyfin.org/stable/",
    // Optional options:
    // accessToken = "access token or api key"
    // clientInfo = ClientInfo(), // defaults to parent info
    // deviceInfo = DeviceInfo(), // defaults to parent info
    // httpClientOptions = HttpClientOptions() // allows setting additional options
)

Authenticating a user

All API operations are grouped. To make use of an operation you need to construct an instance of the
group and give it your API instance.

val userApi = UserApi(api)

try {
    val authenticationResult by userApi.authenticateUserByName(
        username = "demo", 
        password = "",
    )
    
    // Use access token in api instance
    api.accessToken = authenticationResult.accessToken
    
    // Print session information
    println(authenticationResult.sessionInfo)
} catch(err: ApiClientException) {
    // Catch exceptions
    println("Something went wrong! ${err.message}")
}

WebSockets

Jellyfin uses WebSockets to communicate events like library changes and activities. This API can be
used with the special WebSocketApi class.

val webSocketApi = WebSocketApi(api)

// Publish messages
webSocketApi.publish(ActivityLogEntryStartMessage())
webSocketApi.publish(SessionsStartMessage())
webSocketApi.publish(ScheduledTasksInfoStartMessage())

// Listen for messages
webSocketApi.subscribe().collect { message ->
    println(message)
}

Server discovery

The server discovery feature can be used to find servers on the local network, normalize inputted
server addresses and to determine the best server to use from a list of adresses.

// Discover servers on the local network
jellyfin.discovery.discoverLocalServers().collect {
    println("Server ${it.name} was found at address ${it.address}")
}

// Get all candidates for a given input
val candidates = jellyfin.discovery.getAddressCandidates("demo.jellyfin.org/stable")

// Get a flow of potential servers to connect to
val recommended = jellyfin.discovery.getRecommendedServers(candidates, RecommendedServerInfoScore.GOOD)

More examples

We provide a few small projects in the samples folder. The samples are used for testing
new features and can be used as a basis for your own application.

GitHub

https://github.com/jellyfin/jellyfin-sdk-kotlin