Jellyfin Kotlin SDK

https://kotlin-sdk.jellyfin.org/guide/
Admin
The Jellyfin Kotlin SDK provides a comprehensive set of tools and APIs for JVM and Android...
Tokens:5,158
Snippets:41
Trust Score:9.9
Update:8 months ago
Show doc for...
Tokens:
Raw
### Initiate Quick Connect Session (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Demonstrates how to start a Quick Connect session with Jellyfin to authorize a new app using an existing signed-in app. It includes an optional check for Quick Connect enablement on the server and error handling for when it's disabled.

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

// Check if Quick Connect is enabled (this is optional)
val enabled by api.quickConnectApi.getQuickConnectEnabled()
if (!enabled) println("QuickConnect is disabled in the server!")

// Create a Quick Connect session and store the state
try {
	val quickConnectState by api.quickConnectApi.initiateQuickConnect()
} catch (err: InvalidStatusException) {
	if (err.status == 401) {
		// Quick Connect is disabled
		println("QuickConnect is disabled in the server!")
	}
}
```

--------------------------------

### Authentication with Access Token

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Demonstrates how to set an access token when creating an API client instance or by updating an existing client.

```APIDOC
## Setting the Access Token

### Description
When an authentication attempt is successful, the server grants a token. This token can be used in future API requests to authorize the user. In the SDK, this token can be set in two ways.

### Method 1: When creating an API client instance
Use the `accessToken` parameter in the `createApi` function.

### Endpoint
N/A (SDK function)

### Request Example
```kotlin
val api = jellyfin.createApi(
	baseUrl = "https://demo.jellyfin.org/stable/",
	accessToken = "02a7174a4d1843448b6d177d8288efd0",
)
```

### Method 2: By changing the token in an existing API client
Change the token in an existing API client instance using the `update` method.

### Endpoint
N/A (SDK function)

### Request Example
```kotlin
api.update(accessToken = "02a7174a4d1843448b6d177d8288efd0")
```

### Response
N/A (SDK internal state change)
```

--------------------------------

### Discover Jellyfin Servers (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin code demonstrates how to use the server discovery feature to find local Jellyfin servers, get address candidates for a given input, and retrieve a list of recommended servers.

```kotlin
// 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)
```

--------------------------------

### Create Jellyfin Instance (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin code demonstrates how to create an instance of the Jellyfin class using a Kotlin DSL. It requires client information and optionally an Android context.

```kotlin
val jellyfin = createJellyfin {
    clientInfo = ClientInfo(name = "My awesome client!", version = "1.33.7")

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

--------------------------------

### Password Authentication

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Explains how to authenticate a user using their username and password to obtain an access token. Handles invalid credentials with an HTTP 401 error.

```APIDOC
## Password Login

### Description
The password login is the easiest method to implement. Use the `authenticateUserByName` method in the userApi with a username and password combination to get an access token. The server responds with an HTTP 401 status code when the credentials are invalid, otherwise it contains the authentication result with user information.

### Method
`POST` (or equivalent SDK method)

### Endpoint
`/Users/Authenticate` (or equivalent SDK method)

### Parameters
#### Request Body
- **username** (string) - Required - The user's username.
- **password** (string) - Required - The user's password. Leave empty for passwordless users.

### Request Example
```kotlin
val api = jellyfin.createApi(/* .. */)

try {
	val authenticationResult by api.userApi.authenticateUserByName(
		username = "demo",
		password = "",
	)

	// Use access token in api instance
	api.update(accessToken = authenticationResult.accessToken)

	// Print session information
	println(authenticationResult.sessionInfo)
} catch (err: InvalidStatusException) {
	if (err.status == 401) {
		// Username or password is incorrect
		println("Invalid user")
	}
}
```

### Response
#### Success Response (200)
- **accessToken** (string) - The authentication token.
- **user** (object) - User information.
- **sessionInfo** (object) - Information about the current session.

#### Error Response (401)
- Indicates invalid credentials.
```

--------------------------------

### Quick Connect Authentication

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Details the process of using Quick Connect for authentication, which is useful for platforms where entering passwords is inconvenient. It involves initiating a session, displaying a code, and polling for authentication status.

```APIDOC
## Quick Connect

### Description
Using passwords is not the best choice on all platforms. Using the remote of a television or entering a complex password on mobile is not the best experience. For those cases Quick Connect helps out. With Quick Connect the app requests a code from the server and displays it to the user. This code can then be used in an already signed in app to authorize the new one.

The Quick Connect functionality may be disabled by a server. In those cases the server responds with an HTTP 401 response. You can check if QuickConnect is enabled first or deal with it when trying to use it.

### Method
`GET` (for checking enabled status), `POST` (for initiating), `GET` (for checking state), `POST` (for authenticating)

### Endpoint
- `/QuickConnect/Enabled` (or equivalent SDK method)
- `/QuickConnect` (or equivalent SDK method)
- `/Users/AuthenticateQuickConnect` (or equivalent SDK method)

### Parameters
#### Initiate Quick Connect
No specific parameters required for initiation.

#### Get Quick Connect State
- **secret** (string) - Required - The unique code for the Quick Connect session.

#### Authenticate with Quick Connect
- **secret** (string) - Required - The unique code for the Quick Connect session.

### Request Example (Initiation and State Check)
```kotlin
val api = jellyfin.createApi(/* .. */)

// Check if Quick Connect is enabled (this is optional)
val enabled by api.quickConnectApi.getQuickConnectEnabled()
if (!enabled) println("QuickConnect is disabled in the server!")

// Create a Quick Connect session and store the state
try {
	var quickConnectState by api.quickConnectApi.initiateQuickConnect()

	// Update the Quick Connect session state periodically (e.g., every 5 seconds)
	// while (!quickConnectState.authenticated) {
	// 	quickConnectState = api.quickConnectApi.getQuickConnectState(
	// 		secret = quickConnectState.secret,
	// 	)
	// 	Thread.sleep(5000)
	// }

} catch (err: InvalidStatusException) {
	if (err.status == 401) {
		// Quick Connect is disabled
		println("QuickConnect is disabled in the server!")
	}
}
```

### Response
#### Quick Connect Enabled Check
- **enabled** (boolean) - True if Quick Connect is enabled on the server.

#### Initiate Quick Connect / Get Quick Connect State
- **authenticated** (boolean) - True if the user has authorized the app.
- **secret** (string) - A unique code for this session.
- **code** (string) - The code to be displayed to the user.

#### Authenticate with Quick Connect (Success Response - 200)
- **accessToken** (string) - The authentication token.
- **user** (object) - User information.
- **sessionInfo** (object) - Information about the current session.

#### Error Response (401)
- Indicates Quick Connect is disabled on the server.
```

--------------------------------

### Subscribe to All WebSocket Messages (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/websockets

Illustrates subscribing to all available WebSocket message types using the `subscribeAll` function. This approach is less efficient if only a subset of messages is required.

```kotlin
api.webSocket.subscribeAll().collect { message ->
	// type of message is OutboundWebSocketMessage
	println("Received a message: $message")
}
```

--------------------------------

### Authenticate with Quick Connect Secret (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Demonstrates how to obtain an access token after a Quick Connect session has been successfully authenticated by the user. It uses the `authenticateWithQuickConnect` method with the session's secret.

```kotlin
val authenticationResult by api.userApi.authenticateWithQuickConnect(
	secret = quickConnectState.secret,
)

// Use access token in api instance
api.update(accessToken = authenticationResult.accessToken)

// Print session information
println(authenticationResult.sessionInfo)
```

--------------------------------

### Create API Instance and Subscribe to All WebSocket Messages (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/websockets

Demonstrates how to create an authenticated Jellyfin API instance and subscribe to all incoming WebSocket messages. This is useful for general monitoring but not recommended for specific message types.

```kotlin
val api = jellyfin.createApi(baseUrl = "https://demo.jellyfin.org/stable/")

api.webSocket.subscribeAll().collect { message ->
	println(message)
}
```

--------------------------------

### Subscribe to WebSocket Events (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin snippet shows how to subscribe to all WebSocket events from the Jellyfin server using the SocketApi. Received messages are printed to the console.

```kotlin
api.webSocket.subscribeAll().collect { message ->
	println(message)
}
```

--------------------------------

### Set Access Token when Creating API Client (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Demonstrates how to set an access token when initializing the Jellyfin API client using the `createApi` function. This is useful for immediate authenticated access.

```kotlin
val api = jellyfin.createApi(
	baseUrl = "https://demo.jellyfin.org/stable/",
	accessToken = "02a7174a4d1843448b6d177d8288efd0",
)
```

--------------------------------

### Create Jellyfin API Instance (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin snippet shows how to instantiate the API client for Jellyfin. It requires the server's base URL and allows for optional configuration of access tokens, client info, device info, and HTTP client options.

```kotlin
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
)
```

--------------------------------

### Authenticate User and Use Access Token (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin code illustrates how to authenticate a user using their username and password, retrieve an access token, and update the API instance with it. It includes error handling for API client exceptions.

```kotlin
val userApi = api.userApi

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

--------------------------------

### Add Jellyfin Core Dependency to Gradle (Groovy)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This snippet demonstrates how to include the Jellyfin core library in your project using Gradle with Groovy. Replace `$sdkVersion` with the desired SDK version.

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

--------------------------------

### Add Jellyfin Core Dependency to Maven

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This XML snippet illustrates how to add the Jellyfin core library as a dependency in your Maven project. Make sure to set the correct version for `$sdkVersion`.

```xml
<dependency>
  <groupId>org.jellyfin.sdk</groupId>
  <artifactId>jellyfin-core</artifactId>
  <version>$sdkVersion</version>
</dependency>
```

--------------------------------

### Subscribe to Specific WebSocket Message Type (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/websockets

Shows how to subscribe to a specific type of WebSocket message, such as UserDataChangedMessage. This allows for targeted message handling and reduces unnecessary processing.

```kotlin
api.webSocket.subscribe<UserDataChangedMessage>().collect { message ->
	// type of message is UserDataChangedMessage
	println("Received a message: $message")
}
```

--------------------------------

### Update Quick Connect Session State (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Shows how to periodically update the state of an ongoing Quick Connect session to check for user authorization. This is typically done every few seconds until the session is authenticated.

```kotlin
// Update the Quick Connect session state
quickConnectState = api.quickConnectApi.getQuickConnectState(
	secret = quickConnectState.secret,
)
```

--------------------------------

### Configure Gradle for Snapshot Versions (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This Kotlin DSL snippet configures your Gradle build to use snapshot versions of the Jellyfin SDK from the Sonatype snapshots repository. It specifically targets the 'master-SNAPSHOT' release.

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

--------------------------------

### Subscribe to Grouped WebSocket Message Types (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/websockets

Demonstrates subscribing to specific groups of WebSocket messages like general commands, play state, or SyncPlay commands. Filtering by command type is supported.

```kotlin
api.webSocket.subscribeGeneralCommand(GeneralCommandType.DISPLAY_MESSAGE).collect { message ->
	// type of message is GeneralCommandMessage
	println("Received a message: $message")
}

api.webSocket.subscribePlayStateCommands(
	commands = setOf(PlaystateCommand.NEXT_TRACK, PlaystateCommand.PREVIOUS_TRACK)
).collect { message ->
	// type of message is PlaystateMessage
	println("Received a message: $message")
}

api.webSocket.subscribeSyncPlayCommands(
	commands = setOf(SendCommandType.PAUSE, SendCommandType.UNPAUSE)
) { message ->
	// type of message is SyncPlayCommandMessage
	println("Received a message: $message")
}
```

--------------------------------

### Authenticate User by Name with Password (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Illustrates how to authenticate a Jellyfin user using their username and password via the `authenticateUserByName` method. It includes error handling for invalid credentials (HTTP 401) and demonstrates how to use the obtained access token.

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

try {
	val authenticationResult by api.userApi.authenticateUserByName(
		username = "demo",
		password = "",
	)

	// Use access token in api instance
	api.update(accessToken = authenticationResult.accessToken)

	// Print session information
	println(authenticationResult.sessionInfo)
} catch (err: InvalidStatusException) {
	if (err.status == 401) {
		// Username or password is incorrect
		println("Invalid user")
	}
}
```

--------------------------------

### Add Jellyfin Core Dependency to Gradle (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/getting-started

This snippet shows how to add the Jellyfin core library dependency to your project using Gradle with Kotlin DSL. Ensure you have the correct SDK version specified.

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

--------------------------------

### Update Access Token in Existing API Client (Kotlin)

Source: https://kotlin-sdk.jellyfin.org/guide/authentication

Shows how to update the access token for an already created Jellyfin API client instance using the `update` method. This is useful for refreshing or changing authentication tokens.

```kotlin
api.update(accessToken = "02a7174a4d1843448b6d177d8288efd0")
```
Tokens:
Raw