mirror of
https://github.com/jellyfin/jellyfin-sdk-kotlin.git
synced 2024-11-26 23:50:32 +00:00
Use Vitepress to build markdown documentation
This commit is contained in:
Niels van Velzen
Max Rumpf
parent
527030f69a
commit
b577a14f11
@ -15,7 +15,7 @@ ij_kotlin_name_count_to_use_star_import = 1000
|
|||||||
ij_kotlin_name_count_to_use_star_import_for_members = 1000
|
ij_kotlin_name_count_to_use_star_import_for_members = 1000
|
||||||
ij_kotlin_packages_to_use_import_on_demand =
|
ij_kotlin_packages_to_use_import_on_demand =
|
||||||
|
|
||||||
[*.xml]
|
[{*.xml,*.json,*.ts}]
|
||||||
charset = utf-8
|
charset = utf-8
|
||||||
indent_style = tab
|
indent_style = tab
|
||||||
tab_width = 4
|
tab_width = 4
|
||||||
|
|||||||
3
.gitignore
vendored
3
.gitignore
vendored
@ -9,3 +9,6 @@ local.properties
|
|||||||
build/
|
build/
|
||||||
|
|
||||||
java_*.hprof
|
java_*.hprof
|
||||||
|
|
||||||
|
# Docs
|
||||||
|
node_modules
|
||||||
|
|||||||
69
docs/.vitepress/config.ts
Normal file
69
docs/.vitepress/config.ts
Normal file
@ -0,0 +1,69 @@
|
|||||||
|
import { defineConfig } from 'vitepress';
|
||||||
|
|
||||||
|
export default defineConfig({
|
||||||
|
title: 'Jellyfin Kotlin SDK',
|
||||||
|
description: 'Documentation for the Jellyfin Kotlin SDK.',
|
||||||
|
|
||||||
|
themeConfig: {
|
||||||
|
logo: 'jellyfin.svg',
|
||||||
|
siteTitle: 'Kotlin SDK',
|
||||||
|
socialLinks: [
|
||||||
|
{
|
||||||
|
icon: 'github',
|
||||||
|
link: 'https://github.com/jellyfin/jellyfin-sdk-kotlin',
|
||||||
|
}
|
||||||
|
],
|
||||||
|
footer: {
|
||||||
|
message: 'Released under the LGPL-3.0 license.',
|
||||||
|
},
|
||||||
|
|
||||||
|
// Top navigation
|
||||||
|
nav: [
|
||||||
|
{
|
||||||
|
text: 'Guide',
|
||||||
|
link: '/guide/getting-started',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Dokka',
|
||||||
|
link: '/dokka/',
|
||||||
|
},
|
||||||
|
],
|
||||||
|
|
||||||
|
// Side navigation
|
||||||
|
sidebar: [
|
||||||
|
{
|
||||||
|
text: 'Introduction',
|
||||||
|
items: [
|
||||||
|
{
|
||||||
|
text: 'Getting started',
|
||||||
|
link: '/guide/getting-started',
|
||||||
|
},
|
||||||
|
]
|
||||||
|
},
|
||||||
|
|
||||||
|
{
|
||||||
|
text: 'Developing',
|
||||||
|
items: [
|
||||||
|
{
|
||||||
|
text: 'WebSockets',
|
||||||
|
link: '/guide/websockets',
|
||||||
|
},
|
||||||
|
]
|
||||||
|
},
|
||||||
|
|
||||||
|
{
|
||||||
|
text: 'Migrations',
|
||||||
|
items: [
|
||||||
|
{
|
||||||
|
text: 'Migrate to 1.2',
|
||||||
|
link: '/migration/v1.1',
|
||||||
|
},
|
||||||
|
{
|
||||||
|
text: 'Migrate to 1.2',
|
||||||
|
link: '/migration/v1.2',
|
||||||
|
},
|
||||||
|
]
|
||||||
|
}
|
||||||
|
],
|
||||||
|
},
|
||||||
|
});
|
||||||
171
docs/guide/getting-started.md
Normal file
171
docs/guide/getting-started.md
Normal file
@ -0,0 +1,171 @@
|
|||||||
|
# Getting started
|
||||||
|
|
||||||
|
The SDK 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](https://developer.android.com/studio/write/java8-support#library-desugaring).
|
||||||
|
|
||||||
|
## Setup
|
||||||
|
|
||||||
|
Releases are published to `mavenCentral()`. Make sure to use the correct library depending on your
|
||||||
|
platform.
|
||||||
|
|
||||||
|
|
||||||
|
|
||||||
|
**Gradle with Kotlin DSL**
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
implementation("org.jellyfin.sdk:jellyfin-core:$sdkVersion")
|
||||||
|
```
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Gradle with Groovy</summary>
|
||||||
|
|
||||||
|
```groovy
|
||||||
|
implementation "org.jellyfin.sdk:jellyfin-core:$sdkVersion"
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Maven</summary>
|
||||||
|
|
||||||
|
```xml
|
||||||
|
<dependency>
|
||||||
|
<groupId>org.jellyfin.sdk</groupId>
|
||||||
|
<artifactId>jellyfin-core</artifactId>
|
||||||
|
<version>$sdkVersion</version>
|
||||||
|
</dependency>
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
<details>
|
||||||
|
<summary>Using SNAPSHOT versions</summary>
|
||||||
|
|
||||||
|
When working on new features in your application you might need a build of the SDK targeting the next server version.
|
||||||
|
For this use case we publish two SNAPSHOT releases: `master-SNAPSHOT` and `openapi-unstable-SNAPSHOT`. To use the
|
||||||
|
snapshot 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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
repositories {
|
||||||
|
maven("https://s01.oss.sonatype.org/content/repositories/snapshots/") {
|
||||||
|
content {
|
||||||
|
// Only allow SDK snapshots
|
||||||
|
includeVersionByRegex("org\\.jellyfin\\.sdk", ".*", "master-SNAPSHOT")
|
||||||
|
}
|
||||||
|
}
|
||||||
|
}
|
||||||
|
```
|
||||||
|
</details>
|
||||||
|
|
||||||
|
## 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:
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
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.
|
||||||
|
|
||||||
|
```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
|
||||||
|
)
|
||||||
|
```
|
||||||
|
|
||||||
|
### 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.
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val userApi = api.userApi
|
||||||
|
|
||||||
|
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 SocketApi. Documentation is available in the [docs](/docs) folder.
|
||||||
|
|
||||||
|
```kotlin
|
||||||
|
val instance = api.ws()
|
||||||
|
|
||||||
|
instance.addGlobalListener { 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 addresses.
|
||||||
|
|
||||||
|
```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)
|
||||||
|
```
|
||||||
|
|
||||||
|
## More examples
|
||||||
|
|
||||||
|
We provide a few small projects in the [samples](/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](https://github.com/jellyfin/jellyfin-android) is the official Android client for phones and tablets.
|
||||||
|
- [Jellyfin for Android TV](https://github.com/jellyfin/jellyfin-androidtv) is the official Android TV client for Android TV, Nvidia Shield, Amazon Fire TV and Google TV.
|
||||||
|
|
||||||
|
### Third party clients
|
||||||
|
|
||||||
|
- [Findroid](https://github.com/jarnedemeulemeester/findroid) provides a native user interface to browse and play movies and series.
|
||||||
|
|
||||||
|
_Want to add your project? We'd love to know about it, open an issue or create pull request!_
|
||||||
17
docs/index.md
Normal file
17
docs/index.md
Normal file
@ -0,0 +1,17 @@
|
|||||||
|
---
|
||||||
|
layout: home
|
||||||
|
|
||||||
|
hero:
|
||||||
|
name: Jellyfin Kotlin SDK
|
||||||
|
tagline: The Jellyfin Kotlin SDK is a library implementing the Jellyfin API to easily access servers.
|
||||||
|
image:
|
||||||
|
src: jellyfin.svg
|
||||||
|
alt: Jellyfin logo
|
||||||
|
actions:
|
||||||
|
- theme: brand
|
||||||
|
text: Get started
|
||||||
|
link: /guide/getting-started
|
||||||
|
- theme: alt
|
||||||
|
text: View on GitHub
|
||||||
|
link: https://github.com/jellyfin/jellyfin-sdk-kotlin
|
||||||
|
---
|
||||||
34
docs/public/jellyfin.svg
Normal file
34
docs/public/jellyfin.svg
Normal file
@ -0,0 +1,34 @@
|
|||||||
|
<?xml version="1.0" encoding="UTF-8"?>
|
||||||
|
<!-- ***** BEGIN LICENSE BLOCK *****
|
||||||
|
- Part of the Jellyfin project (https://jellyfin.media)
|
||||||
|
-
|
||||||
|
- All copyright belongs to the Jellyfin contributors; a full list can
|
||||||
|
- be found in the file CONTRIBUTORS.md
|
||||||
|
-
|
||||||
|
- This work is licensed under the Creative Commons Attribution-ShareAlike 4.0 International License.
|
||||||
|
- To view a copy of this license, visit http://creativecommons.org/licenses/by-sa/4.0/.
|
||||||
|
- ***** END LICENSE BLOCK ***** -->
|
||||||
|
<svg id="banner-dark" xmlns="http://www.w3.org/2000/svg" xmlns:xlink="http://www.w3.org/1999/xlink" viewBox="0 0 1536 512">
|
||||||
|
<defs>
|
||||||
|
<linearGradient id="linear-gradient" x1="110.25" y1="213.3" x2="496.14" y2="436.09" gradientUnits="userSpaceOnUse">
|
||||||
|
<stop offset="0" stop-color="#aa5cc3"/>
|
||||||
|
<stop offset="1" stop-color="#00a4dc"/>
|
||||||
|
</linearGradient>
|
||||||
|
</defs>
|
||||||
|
<title>banner-dark</title>
|
||||||
|
<g id="banner-dark">
|
||||||
|
<g id="banner-dark-icon">
|
||||||
|
<path id="inner-shape" d="M261.42,201.62c-20.44,0-86.24,119.29-76.2,139.43s142.48,19.92,152.4,0S281.86,201.63,261.42,201.62Z" fill="url(#linear-gradient)"/>
|
||||||
|
<path id="outer-shape" d="M261.42,23.3C199.83,23.3,1.57,382.73,31.8,443.43s429.34,60,459.24,0S323,23.3,261.42,23.3ZM411.9,390.76c-19.59,39.33-281.08,39.77-300.9,0S221.1,115.48,261.45,115.48,431.49,351.42,411.9,390.76Z" fill="url(#linear-gradient)"/>
|
||||||
|
</g>
|
||||||
|
<g id="jellyfin-light-outlines" style="isolation:isolate" transform="translate(43.8)">
|
||||||
|
<path d="M556.64,350.75a67,67,0,0,1-22.87-27.47,8.91,8.91,0,0,1-1.49-4.75,7.42,7.42,0,0,1,2.83-5.94,9.25,9.25,0,0,1,6.09-2.38c3.16,0,5.94,1.69,8.31,5.05a48.09,48.09,0,0,0,16.34,20.34,40.59,40.59,0,0,0,24,7.58q20.51,0,33.27-12.62t12.77-33.12V159a8.44,8.44,0,0,1,2.67-6.39,9.56,9.56,0,0,1,6.83-2.52,9,9,0,0,1,6.68,2.52,8.7,8.7,0,0,1,2.53,6.39v138.4a64.7,64.7,0,0,1-8.32,32.67,59,59,0,0,1-23,22.72Q608.62,361,589.9,361A57.21,57.21,0,0,1,556.64,350.75Z" fill="#fff"/>
|
||||||
|
<path d="M831.66,279.47a8.77,8.77,0,0,1-6.24,2.53H713.16q0,17.82,7.27,31.92a54.91,54.91,0,0,0,20.79,22.28q13.51,8.18,31.93,8.17a54,54,0,0,0,25.54-5.94,52.7,52.7,0,0,0,18.12-15.15,10,10,0,0,1,6.24-2.67,8.14,8.14,0,0,1,7.72,7.72,8.81,8.81,0,0,1-3,6.24,74.7,74.7,0,0,1-23.91,19A65.56,65.56,0,0,1,773.45,361q-22.87,0-40.4-9.8a69.51,69.51,0,0,1-27.32-27.48q-9.79-17.66-9.8-40.83,0-24.36,9.65-42.62t25.69-27.92a65.2,65.2,0,0,1,34.16-9.65A70,70,0,0,1,798.84,211a65.78,65.78,0,0,1,25.39,24.36q9.81,16,10.1,38A8.07,8.07,0,0,1,831.66,279.47ZM733.5,231.8Q718.8,243.68,714.64,266H815.92v-2.38A46.91,46.91,0,0,0,807,240.27a48.47,48.47,0,0,0-18.56-15.15,54,54,0,0,0-23-5.2Q748.2,219.92,733.5,231.8Z" fill="#fff"/>
|
||||||
|
<path d="M888.24,355.5a8.92,8.92,0,0,1-15.3-6.38v-202a8.91,8.91,0,1,1,17.82,0v202A8.65,8.65,0,0,1,888.24,355.5Z" fill="#fff"/>
|
||||||
|
<path d="M956.55,355.5a8.92,8.92,0,0,1-15.3-6.38v-202a8.91,8.91,0,1,1,17.82,0v202A8.65,8.65,0,0,1,956.55,355.5Z" fill="#fff"/>
|
||||||
|
<path d="M1122.86,206.11a8.7,8.7,0,0,1,2.53,6.39v131q0,23.44-9.21,40.09a61.58,61.58,0,0,1-25.54,25.25q-16.34,8.61-36.83,8.61a96.73,96.73,0,0,1-23.31-2.68,61.72,61.72,0,0,1-18-7.12q-6.24-3.87-6.24-8.62a17.94,17.94,0,0,1,.6-3,8.06,8.06,0,0,1,3-4.45,7.49,7.49,0,0,1,4.45-1.49,7.91,7.91,0,0,1,3.56.89q19,10.39,36.24,10.4,24.65,0,39.06-15.44t14.4-42.18V333.38a54.37,54.37,0,0,1-21.38,20,62.55,62.55,0,0,1-30.3,7.58q-25.83,0-39.2-15.45t-13.37-41.87V212.5a8.91,8.91,0,1,1,17.82,0V301q0,21.39,9.36,32.38t29.25,11a48,48,0,0,0,23.32-6.09,49.88,49.88,0,0,0,17.82-16,37.44,37.44,0,0,0,6.68-21.24V212.5a9,9,0,0,1,15.29-6.39Z" fill="#fff"/>
|
||||||
|
<path d="M1210.18,161.41q-5.21,6.24-5.2,17.23v30.59h33.27a8.19,8.19,0,0,1,5.79,2.38,8.26,8.26,0,0,1,0,11.88,8.22,8.22,0,0,1-5.79,2.37H1205V349.12a8.91,8.91,0,1,1-17.82,0V225.86h-21.68a7.83,7.83,0,0,1-5.94-2.52,8.21,8.21,0,0,1-2.37-5.79,8,8,0,0,1,2.37-6.09,8.33,8.33,0,0,1,5.94-2.23h21.68V178.64q0-18.7,10.84-29t29-10.24a46.1,46.1,0,0,1,15.45,2.52q7.13,2.53,7.12,8.17a8.07,8.07,0,0,1-2.37,5.94,7.37,7.37,0,0,1-5.35,2.37,18.81,18.81,0,0,1-6.53-1.48,42,42,0,0,0-10.4-1.78Q1215.37,155.18,1210.18,161.41ZM1276,180.87c-2.19-1.88-3.27-4.61-3.27-8.17v-3q0-5.34,3.41-8.17t9.36-2.82q11.88,0,11.88,11v3c0,3.56-1,6.29-3.12,8.17s-5.1,2.82-9.06,2.82S1278.14,182.75,1276,180.87Zm15.59,174.63a8.92,8.92,0,0,1-15.3-6.38V212.5a8.91,8.91,0,1,1,17.82,0V349.12A8.65,8.65,0,0,1,1291.56,355.5Z" fill="#fff"/>
|
||||||
|
<path d="M1452.53,218.88q12.92,16.2,12.92,42.92v87.32a8.4,8.4,0,0,1-2.67,6.38,8.8,8.8,0,0,1-6.24,2.53,8.64,8.64,0,0,1-8.91-8.91V262.69q0-19.31-9.65-31.33t-29.85-12a53.28,53.28,0,0,0-42.77,21.83,36.24,36.24,0,0,0-7.13,21.53v86.43a8.91,8.91,0,1,1-17.82,0V216.06a8.91,8.91,0,1,1,17.82,0V232.4q8-12.77,23-21.24A61.84,61.84,0,0,1,1412,202.7Q1439.61,202.7,1452.53,218.88Z" fill="#fff"/>
|
||||||
|
</g>
|
||||||
|
</g>
|
||||||
|
</svg>
|
||||||
|
After Width: | Height: | Size: 4.7 KiB |
1144
package-lock.json
generated
Normal file
1144
package-lock.json
generated
Normal file
File diff suppressed because it is too large
Load Diff
10
package.json
Normal file
10
package.json
Normal file
@ -0,0 +1,10 @@
|
|||||||
|
{
|
||||||
|
"description": "This file is used for the documentation only",
|
||||||
|
"scripts": {
|
||||||
|
"start": "vitepress dev docs",
|
||||||
|
"build": "vitepress build docs"
|
||||||
|
},
|
||||||
|
"devDependencies": {
|
||||||
|
"vitepress": "1.0.0-alpha.12"
|
||||||
|
}
|
||||||
|
}
|
||||||
Loading…
Reference in New Issue
Block a user