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!
2 Dec 14, 2022
8 Nov 2, 2022
14 Nov 15, 2022
4 Aug 6, 2022
2 May 8, 2022
28 Nov 14, 2022
8 Dec 3, 2021
24 Aug 20, 2022
83 Oct 30, 2022
4 May 10, 2022
8 Jul 12, 2022
522 Jan 3, 2023
1 Sep 2, 2022
1k Dec 30, 2022
2 Nov 8, 2021
121 Dec 26, 2022
236 Nov 30, 2022
18 Apr 21, 2022