jellyfin-sdk-kotlin/README.md

Jellyfin Kotlin SDK

Part of the Jellyfin Project

---

---

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.

Gradle with Kotlin DSL

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

Gradle with Groovy

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

Maven

<dependency>
    <groupId>org.jellyfin.sdk</groupId>
    <artifactId>jellyfin-core</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 = createJellyfin {
    clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7",)

    // Uncomment when using android:
    // context = /* Android Context */
}

Make sure to supply the client information if you want to make API calls. The context is required for Android applications.

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 first get the group from your ApiClient instance. All groups are defined as extension functions and you can alternatively construct the API instances manually.

val userApi = api.userApi
// or
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.

// 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.

Projects using the SDK

Official Jellyfin clients

• Jellyfin for Android is the official Android client for phones and tablets.
• Jellyfin for Android TV is the official Android TV client for Android TV, Nvidia Shield, Amazon Fire TV and Google TV.

Third party clients

• Gelli is a music-focused Android client.

Want to add your project? Please create a pull request!