jellyfin-sdk-kotlin

This release brings a temporary fix for a badly generated type in the TranscodingInfo model causing the JSON deserialization to fail.

Bugfixes

• Add TranscodingInfoTranscodeReasonsHook to fix issue with OpenAPI spec #542, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

In this release we have fixed two small bugs and updated the API to Jellyfin 10.8.5. This API version adds the "data" member to the "MediaStreamType" enum.

Features

• Update OpenAPI to 10.8.5 #521, by @nielsvanvelzen

Bugfixes

• Fix AddressCandidateHelper issues with empty input and invalid ports #491, by @nielsvanvelzen
• Fallback to manufacturer + model when device name is null #508, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

This release fixes device names with special characters, updates the API to Jellyfin 10.8.4 (no changes) and adds constants for CollectionType, ItemSortBy, MediaType and PersonType.

Changelog

• Use URL encoding for authorization header values #457, by @nielsvanvelzen
• Update OpenAPI to 10.8.4 #461, by @jellyfin-bot
• Add model constants CollectionType, ItemSortBy, MediaType and PersonType #462, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot

Compatibility

SSL exceptions are now handled by the ApiClient, fixing a regression of the previous 1.3.3 release that caused clients to crash. The recommended server version is bumped to 10.8.3 (although it does not contain any API changes).

Changelog

• Update OpenAPI to 10.8.3 #447, by @jellyfin-bot
• Add SecureConnectionException for all SSL related exceptions #449, by @nielsvanvelzen
• Catch all ApiClientException instances in RecommendedServerDiscovery #450, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot

Compatibility

This release fixes an issue where the ApiClient caught all throwables and rethrow them wrapped as ApiClientException. This behavior caused issues with Kotlin coroutines because the CancellationException was changed to a different exception type.

Changelog

• Remove catching (too generic) Throwable exceptions #446, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

Fixed an issue where java.net.ConnectException was not mapped to the SDK's TimeoutException and adds two tiny features:

1. Accept "minimumServerVersion" in JellyfinOptions to forcefully support older Jellyfin versions
2. Add clientLogApi.logFileUrl to generate the URL used for crash reports

Changelog

• Generate URL builder function for ClientLogApi.logFile #432, by @nielsvanvelzen
• Allow client to change minimum server version #434, by @nielsvanvelzen
• Map java.net.ConnectException to TimeoutException #442, by @AndreasGB

Contributors

• @nielsvanvelzen
• @AndreasGB

Compatibility

Jellyfin 10.8.1 was released with a few changes to the API. Unfortunately this includes some breaking changes. Keep using the previous SDK release (1.3.0) If you'd like to support 10.8.0 or don't need the changes from this release.

The breaking changes in the API are:

• Added splashscreenEnabled field in BrandingOptions
• Added vppTonemappingBrightness and vppTonemappingContrast fields in EncodingOptions

The mentioned API models will cause an exception when using 10.8.0 or lower because they lack a value in the API responses and have no defaults set.

Changelog

• Update kotest to v5.3.1 #418, by @renovate[bot]
• Update dependency com.squareup:kotlinpoet to v1.12.0 #419, by @renovate[bot]
• Increase minimum supported Jellyfin version to 10.8.1 #423, by @nielsvanvelzen
• Update kotest to v5.3.2 #429, by @renovate[bot]
• Update OpenAPI to 10.8.1 #431, by @jellyfin-bot

Contributors

• @renovate[bot]
• @nielsvanvelzen
• @jellyfin-bot

Compatibility

Jellyfin 10.8 was just released! This version of the SDK builds on top of the API changes and guarantees compatibility. The SDK now requires the server to use 10.8 or newer because of some incompatible changes in the WebSocket code and stricter nullability in the API. We recommend using a previous SDK version (like 1.2) if you still want or need to support Jellyfin 10.7.

Significant changes in this release include:

• WebSocket code now authenticates via HTTP header instead of URL (incompatible with 10.7)
• Lot's of nullability fixes in the API code
• More enums in the API (BaseItemKind is an exiting one here)

Changelog

• Add generator task for stable-pre openapi files #364, by @nielsvanvelzen
• Use JsonElement type for empty schema #367, by @nielsvanvelzen
• Remove old WebSocket implementation #369, by @nielsvanvelzen
• Bump actions/setup-java from 2 to 3 #374, by @dependabot[bot]
• Update dependencies #376, by @nielsvanvelzen
• Use Authorization header for WebSocket connections #377, by @nielsvanvelzen
• Update OpenAPI to 10.8.0-beta.1 #378, by @nielsvanvelzen
• Update minimumVersion to 10.8 #379, by @nielsvanvelzen
• Update OpenAPI to 10.8.0-beta.2 #380, by @nielsvanvelzen
• Fix ServerVersion comparison failing when build is not set #381, by @nielsvanvelzen
• Add extension function for authenticateWithQuickConnect that takes the secret directly #382, by @nielsvanvelzen
• Configure Renovate #384, by @renovate[bot]
• Move dependency repository definition to build.gradle.kts #385, by @nielsvanvelzen
• Delete dependabot.yml #386, by @nielsvanvelzen
• Update dependency com.github.ajalt.clikt:clikt to v3.4.2 #387, by @renovate[bot]
• Update org.jetbrains.kotlin to v1.6.21 #388, by @renovate[bot]
• Update plugin dokka to v1.6.21 #389, by @renovate[bot]
• Update plugin kotlin-serialization to v1.6.21 #390, by @renovate[bot]
• Update plugin binarycompatibilityvalidator to v0.9.0 #392, by @renovate[bot]
• Update github/codeql-action action to v2 #393, by @renovate[bot]
• Fix invalid string and binary request bodies #395, by @nielsvanvelzen
• Migrate unit tests to Kotest #396, by @nielsvanvelzen
• Update kotest to v5.3.0 #399, by @renovate[bot]
• Update dependency io.insert-koin:koin-core to v3.2.0 #403, by @renovate[bot]
• Update dependency org.jetbrains.kotlinx:kotlinx-serialization-json to v1.3.3 #405, by @renovate[bot]
• Update dependency org.jetbrains.kotlinx.binary-compatibility-validator to v0.10.0 #406, by @renovate[bot]
• Update dependency io.github.microutils:kotlin-logging to v2.1.23 #407, by @renovate[bot]
• Pin dependencies #408, by @renovate[bot]
• Update dependency io.swagger.parser.v3:swagger-parser to v2.0.33 #409, by @renovate[bot]
• Set input/output in openapi-generator tasks #411, by @nielsvanvelzen
• Update Kotlin to v1.6.2 #412, by @renovate[bot]
• Update github/codeql-action digest to 27ea8f8 #413, by @renovate[bot]
• Update dependency androidx.core:core-ktx to v1.8.0 #414, by @renovate[bot]
• Update OpenAPI to 10.8.0 #416, by @jellyfin-bot

Contributors

• @renovate[bot]
• @nielsvanvelzen
• @dependabot[bot]
• @jellyfin-bot

Compatibility

This beta bumps the versions of our used libraries and fixes an issue in POST requests (#395) that use binary data or text instead of JSON. No changes to the API in this beta.

Changelog

• Configure Renovate #384, by @renovate[bot]
• Move dependency repository definition to build.gradle.kts #385, by @nielsvanvelzen
• Delete dependabot.yml #386, by @nielsvanvelzen
• Update dependency com.github.ajalt.clikt:clikt to v3.4.2 #387, by @renovate[bot]
• Update org.jetbrains.kotlin to v1.6.21 #388, by @renovate[bot]
• Update plugin dokka to v1.6.21 #389, by @renovate[bot]
• Update plugin kotlin-serialization to v1.6.21 #390, by @renovate[bot]
• Update plugin binarycompatibilityvalidator to v0.9.0 #392, by @renovate[bot]
• Update github/codeql-action action to v2 #393, by @renovate[bot]
• Fix invalid string and binary request bodies #395, by @nielsvanvelzen
• Migrate unit tests to Kotest #396, by @nielsvanvelzen
• Update kotest to v5.3.0 #399, by @renovate[bot]
• Update dependency io.insert-koin:koin-core to v3.2.0 #403, by @renovate[bot]
• Update dependency org.jetbrains.kotlinx:kotlinx-serialization-json to v1.3.3 #405, by @renovate[bot]

Contributors

• @renovate[bot]
• @nielsvanvelzen

Compatibility

I'm excited to announce version 1.2.0 of the Jellyfin Kotlin SDK. This is a relatively small release compared to the previous
v1.1.0 release. Highlights of this release are:

• Completely rewritten WebSocket API which is easier to use and more stable
• Refactored helper functions for Java compatibility
• Extension functions for GeneralCommandMessage
• Ability to change device info on Android platform

Read the migration guide at /docs/migration/v1.2.md or the WebSocket guide at /docs/websockets.md to get started
with this release.

Changelog

• Add extensions to read arguments from GeneralCommandMessage #335, by @nielsvanvelzen
• Update Gradle Wrapper from 7.2 to 7.3 #336, by @jellyfin-bot
• Update Gradle Wrapper from 7.3 to 7.3.1 #337, by @jellyfin-bot
• Add compatibility util to collect flows from Java #338, by @GiviMAD
• Update dependencies (includes upgrade to Kotlin 1.6.10) #339, by @nielsvanvelzen
• Update Gradle Wrapper from 7.3.1 to 7.3.2 #340, by @jellyfin-bot
• Update Gradle Wrapper from 7.3.2 to 7.3.3 #343, by @jellyfin-bot
• Disable wildcard imports #344, by @nielsvanvelzen
• Update @OptIn usages #345, by @nielsvanvelzen
• Rewrite Java callback helpers to support error handling and non-api functions #346, by @nielsvanvelzen
• Deprecate WebSocketApi #349, by @nielsvanvelzen
• Support username and password arguments in kotlin-cli sample #350, by @nielsvanvelzen
• WebSocket API rewrite #352, by @nielsvanvelzen
• Allow custom device info in Android target #353, by @nielsvanvelzen
• Update Gradle Wrapper from 7.3.3 to 7.4 #355, by @jellyfin-bot
• Bump actions/checkout from 2 to 3 #356, by @dependabot[bot]
• Update Gradle Wrapper from 7.4 to 7.4.1 #357, by @jellyfin-bot
• Add MissingBaseUrlException to replace IllegalArgumentException #358, by @nielsvanvelzen
• Update KotlinPoet to 1.11.0 #359, by @nielsvanvelzen
• Add mutex for updateConnectionState to prevent unnecessary reconnects #362, by @nielsvanvelzen
• Don't throw when baseUrl not set in SocketInstance #363, by @nielsvanvelzen
• Update Gradle Wrapper from 7.4.1 to 7.4.2 #365, by @jellyfin-bot
• Add OkHttpWebsocketSession for JVM and Android targets #366, by @nielsvanvelzen
• Update @OptIn annotations #368, by @nielsvanvelzen
• Update README #370, by @nielsvanvelzen
• Remove KtorSocketInstanceConnection #371, by @nielsvanvelzen
• Rewrite/simplify internal WebSocket message sending #372, by @nielsvanvelzen
• Add retry logic to SocketInstance #373, by @nielsvanvelzen
• Fix ServerVersion comparison failing when build is not set #381, by @nielsvanvelzen
• Add migration document for v1.2 #383, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot
• @GiviMAD
• @dependabot[bot]

Compatibility

This second beta updates the generated API to the second beta for 10.8. It also adds a new utility extension function for Quick Connect implementations and a bugfix in the ServerVersion comparator.

Changelog

• Update OpenAPI to 10.8.0-beta.2 #380, by @nielsvanvelzen
• Fix ServerVersion comparison failing when build is not set #381, by @nielsvanvelzen
• Add extension function for authenticateWithQuickConnect that takes the secret directly #382, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

This release is binary compatible with the previous beta. If no new issues are found the 1.2.0 release should follow within a few weeks.

Changelog

• Fix ServerVersion comparison failing when build is not set #381, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

This is the first beta for the 1.3.0 version of the SDK. This release only supports Jellyfin 10.8 or newer. The WebSocket code in this version does not work with 10.7 based servers because of authentication changes. The most significant changes in the API are nullability fixes and the introduction of the BaseItemKind enum. Upgrading should be fairly straightforward.

Changelog

• Add generator task for stable-pre openapi files #364, by @nielsvanvelzen
• Use JsonElement type for empty schema #367, by @nielsvanvelzen
• Remove old WebSocket implementation #369, by @nielsvanvelzen
• Bump actions/setup-java from 2 to 3 #374, by @dependabot[bot]
• Update dependencies #376, by @nielsvanvelzen
• Use Authorization header for WebSocket connections #377, by @nielsvanvelzen
• Update OpenAPI to 10.8.0-beta.1 #378, by @nielsvanvelzen
• Update minimumVersion to 10.8 #379, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @dependabot[bot]

Compatibility

The WebSocket code now reconnects automatically and a bunch of bugfixes were made to make it more reliable. The most significant change in this beta is the move from Ktor to OkHttp as the backend for the socket code. This release is binary compatible with the previous beta, except for some smaller internal API's that are unlikely to be used directly. If no new issues are found the 1.2.0 release should follow within a few weeks.

Changelog

• Add mutex for updateConnectionState to prevent unnecessary reconnects #362, by @nielsvanvelzen
• Don't throw when baseUrl not set in SocketInstance #363, by @nielsvanvelzen
• Update Gradle Wrapper from 7.4.1 to 7.4.2 #365, by @jellyfin-bot
• Add OkHttpWebsocketSession for JVM and Android targets #366, by @nielsvanvelzen
• Update @OptIn annotations #368, by @nielsvanvelzen
• Update README #370, by @nielsvanvelzen
• Remove KtorSocketInstanceConnection #371, by @nielsvanvelzen
• Rewrite/simplify internal WebSocket message sending #372, by @nielsvanvelzen
• Add retry logic to SocketInstance #373, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot

Compatibility

This is the initial beta for the upcoming 1.2.0 release. The focus for this release was rewriting the WebSocket code. It's not ready for production use until we fix a few known bugs and missing features (unnecessary reconnects on subscription changes and the lack of automatic reconnection logic). However, everything else in this beta is stable and unlikely to change until release.

Changelog

• Add extensions to read arguments from GeneralCommandMessage #335, by @nielsvanvelzen
• Update Gradle Wrapper from 7.2 to 7.3 #336, by @jellyfin-bot
• Update Gradle Wrapper from 7.3 to 7.3.1 #337, by @jellyfin-bot
• Add compatibility util to collect flows from Java #338, by @GiviMAD
• Update dependencies (includes upgrade to Kotlin 1.6.10) #339, by @nielsvanvelzen
• Update Gradle Wrapper from 7.3.1 to 7.3.2 #340, by @jellyfin-bot
• Update Gradle Wrapper from 7.3.2 to 7.3.3 #343, by @jellyfin-bot
• Disable wildcard imports #344, by @nielsvanvelzen
• Update @OptIn usages #345, by @nielsvanvelzen
• Rewrite Java callback helpers to support error handling and non-api functions #346, by @nielsvanvelzen
• Deprecate WebSocketApi #349, by @nielsvanvelzen
• Support username and password arguments in kotlin-cli sample #350, by @nielsvanvelzen
• WebSocket API rewrite #352, by @nielsvanvelzen
• Allow custom device info in Android target #353, by @nielsvanvelzen
• Update Gradle Wrapper from 7.3.3 to 7.4 #355, by @jellyfin-bot
• Bump actions/checkout from 2 to 3 #356, by @dependabot[bot]
• Update Gradle Wrapper from 7.4 to 7.4.1 #357, by @jellyfin-bot
• Add MissingBaseUrlException to replace IllegalArgumentException #358, by @nielsvanvelzen
• Update KotlinPoet to 1.11.0 #359, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot
• @GiviMAD
• @dependabot[bot]

Compatibility

This is a bugfix release for the 1.1.0 release. We've found an issue with the DisplayPreferencesDto model in the 10.7 API specification and made a temporary fix by using the type from the 10.8 API specification. Another issue where JSON deserialization problems would not use the ApiClientException was also fixed.

Changelog

• Fix SerializationException not catched in RawResponse #347, by @nielsvanvelzen
• Add DisplayPreferencesDtoNullabilityFixHook #348, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

This is a bugfix release for the 1.1.0 release. We've identified and fixed an issue where our API generator ignored the request body data type. This caused various image uploading endpoints to not work. We've also removed a duplicate WebSocket enum (GeneralCommandType). You might need to update some of your imports for this change.

Changelog

• Use generated GeneralCommandType model #332, by @nielsvanvelzen
• Fix generator ignoring non-json request body types #334, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility

Thousands of Jellyfin users are now using the Kotlin SDK to communicate with their Jellyfin servers. Today we're releasing a new version with changes based on the feedback we collected from ourselves and the community apps.

The biggest change with v1.1.0 is the switch to Kotlin Multiplatform. With this change we can now write different code for specific platforms. We're already using this for the Android platform, making it easier to get started with the SDK! Other significant updates include the addition of API extensions, to make it easier to call the various API's. And the server discovery feature now returning more information about why it can't connect to a server.

Read all about the new features and how to migrate your existing code in the documentation at /docs/migration/v1.1.md.

Changelog

• Miscellaneous build script changes #289, by @nielsvanvelzen
• Fix all linter issues from 1.0.z release #290, by @nielsvanvelzen
• Use collection type for operation parameters #291, by @nielsvanvelzen
• Add ParameterValidation framework with initial IntRangeValidation #292, by @nielsvanvelzen
• Correctly set member names in OperationBuilder #293, by @nielsvanvelzen
• Emit issue information in RecommendedServerDiscovery #296, by @nielsvanvelzen
• Update Android Gradle Plugin to 7.0.0 #298, by @nielsvanvelzen
• WebSocketApi fixes #299, by @nielsvanvelzen
• Move generator types to constants and typealias JVM types #301, by @nielsvanvelzen
• Convert jellyfin-model to Kotlin Multiplatform #302, by @nielsvanvelzen
• Replace slf4j with kotlin-logging #303, by @nielsvanvelzen
• Convert jellyfin-api to Kotlin Multiplatform #304, by @nielsvanvelzen
• Update Gradle Wrapper from 7.1.1 to 7.2 #305, by @jellyfin-bot
• Use Gradle Dependency Catalog for plugins #306, by @nielsvanvelzen
• Use dokkaHtml instead of dokkaJavadoc for published documentation #307, by @nielsvanvelzen
• Convert jellyfin-core and jellyfin-platform-android to Kotlin Multiplatform #308, by @nielsvanvelzen
• Update Detekt to 1.18.0 #309, by @nielsvanvelzen
• Add verify function to openapi-generator #310, by @nielsvanvelzen
• Rename main to commonMain #311, by @nielsvanvelzen
• Update README for multiplatform changes #312, by @nielsvanvelzen
• Set proper name in POM files #313, by @nielsvanvelzen
• Move ApiClient HTTP methods to extension functions #314, by @nielsvanvelzen
• Update dependencies #315, by @nielsvanvelzen
• Use actions/setup-java caching #316, by @nielsvanvelzen
• Checkout repository in sdk-update-api-spec workflow #317, by @nielsvanvelzen
• Add ApiClientFactory option to allow different http clients #318, by @nielsvanvelzen
• Add url and path building to new UrlBuilder #319, by @nielsvanvelzen
• Update OpenAPI to 10.7.7 #320, by @jellyfin-bot
• Use Java 17 as default and move to Adoptium distribution #321, by @nielsvanvelzen
• Separate content (de)serialization from ApiClient #322, by @nielsvanvelzen
• Add cause to custom exception classes #323, by @nielsvanvelzen
• Add Api instances to ApiClient as extension properties #324, by @nielsvanvelzen
• Add v1.1 migration documentation #325, by @nielsvanvelzen
• Update binary-compatibility-validator to 0.8.0-RC and re-enable jellyfin-core api validation again #326, by @nielsvanvelzen
• Fix ApiSerializer for Unit type #327, by @nielsvanvelzen
• Use testutils in all modules #328, by @nielsvanvelzen
• Add tests for PairExtensions #329, by @nielsvanvelzen
• Update all dependencies to latest version #330, by @nielsvanvelzen
• Require explicit enabling of publishing #331, by @nielsvanvelzen

Contributors

• @nielsvanvelzen
• @jellyfin-bot

Compatibility

Jellyfin 10.7.7 adds back the maxWidth and maxHeight parameters in various playback related endpoints. There are no other changes in this version. See https://github.com/jellyfin/jellyfin/pull/6274 for more information about this change.

Changelog

• Update OpenAPI to 10.7.7 #320, by @jellyfin-bot

Contributors

• @jellyfin-bot

Compatibility

We've identified and fixed an issue in the SDK for Android apps that use ProGuard or R8.

Changelog

• Workaround for server connection failure on Android #300, by @nielsvanvelzen

Contributors

• @nielsvanvelzen

Compatibility