Player

Development These docs follow the development version and change with every merge.

Last updated View as Markdown

The player API for audiobook apps written for an Audiobookshelf server (docs/server/player-apps.md).

Back to the web API reference.

GET /player/status

Tells an app what the server is before it offers a sign-in.

Answers without a card: the version of the API it speaks and the sign-in methods an app may offer (a player password, and the browser sign-in).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200What an app checks before it offers a sign-in. Body: Status (application/json)6 fields
    • appstringrequiredAlways [STATUS_APP].
    • serverVersionstringrequiredThe server release whose API this one answers like ([crate::COMPATIBLE_SERVER_VERSION]).
    • isInitbooleanrequiredAlways true: the library is set up before an app can sign in.
    • languagestringrequiredThe interface language apps show server text in.
    • authMethodsarray of stringrequired[AUTH_METHODS].
    • authFormDataAuthFormDatarequiredWhat the sign-in screen shows.

Example request

$ curl 'http://127.0.0.1:8787/player/status'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/status'
import requests

response = requests.get("http://127.0.0.1:8787/player/status")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/status");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/status").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: What an app checks before it offers a sign-in.

{
  "app": "audiobookshelf",
  "serverVersion": "2.17.0",
  "isInit": true,
  "language": "en-us",
  "authMethods": [
    "local",
    "openid"
  ],
  "authFormData": {
    "authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
    "authOpenIDButtonText": "Sign in with the library",
    "authOpenIDAutoLaunch": false
  }
}

Schema:

{
  "type": "object",
  "description": "`GET /status`: what an app asks before it signs in.",
  "required": [
    "app",
    "serverVersion",
    "isInit",
    "language",
    "authMethods",
    "authFormData"
  ],
  "properties": {
    "app": {
      "type": "string",
      "description": "Always [`STATUS_APP`].",
      "example": "audiobookshelf"
    },
    "serverVersion": {
      "type": "string",
      "description": "The server release whose API this one answers like\n([`crate::COMPATIBLE_SERVER_VERSION`]).",
      "example": "2.17.0"
    },
    "isInit": {
      "type": "boolean",
      "description": "Always true: the library is set up before an app can sign in.",
      "example": true
    },
    "language": {
      "type": "string",
      "description": "The interface language apps show server text in.",
      "example": "en-us"
    },
    "authMethods": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "[`AUTH_METHODS`].",
      "example": [
        "local",
        "openid"
      ]
    },
    "authFormData": {
      "type": "object",
      "description": "What the sign-in screen shows.",
      "required": [
        "authOpenIDButtonText",
        "authOpenIDAutoLaunch"
      ],
      "properties": {
        "authLoginCustomMessage": {
          "type": [
            "string",
            "null"
          ],
          "description": "A note under the sign-in form: where to get a player password.",
          "example": "Sign in with a player password from Settings, Account, Player apps."
        },
        "authOpenIDButtonText": {
          "type": "string",
          "description": "The label of the browser sign-in button.",
          "example": "Sign in with the library"
        },
        "authOpenIDAutoLaunch": {
          "type": "boolean",
          "description": "Whether apps open the browser sign-in without a tap: never.",
          "example": false
        }
      }
    }
  }
}

GET /player/ping

Answers that the player API is up, without a card.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200The API answers. Body: Ping (application/json)1 field
    • successbooleanrequiredAlways true.

Example request

$ curl 'http://127.0.0.1:8787/player/ping'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/ping'
import requests

response = requests.get("http://127.0.0.1:8787/player/ping")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/ping");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/ping").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The API answers.

{
  "success": true
}

Schema:

{
  "type": "object",
  "description": "`GET /ping`: `{ \"success\": true }`.",
  "required": [
    "success"
  ],
  "properties": {
    "success": {
      "type": "boolean",
      "description": "Always true.",
      "example": true
    }
  }
}

GET /player/healthcheck

Answers OK in plain text, without a card, for apps that check health.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Responses

  • 200OK. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/healthcheck'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/healthcheck'
import requests

response = requests.get("http://127.0.0.1:8787/player/healthcheck")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/healthcheck");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/healthcheck").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

POST /player/login

Signs an app in with a username and a player password.

The username is the patron's sign-in name or email; the password is a player password from Account settings, never the account password.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Request body

The sign-in name (or email) and a player password.

application/json: LoginBody

  • usernamestringrequiredThe patron's sign-in name or email address.
  • passwordstringrequiredA player password from Account settings; the account password is never accepted.

Responses

  • 200The patron, the card's tokens and settings. Body: PlayerLoginResponse (application/json)5 fields
    • userUserrequiredThe signed-in patron, with the card's tokens.
    • userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.
    • serverSettingsServerSettingsrequiredSettings apps read at sign-in.
    • ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.
    • SourcestringrequiredHow the server was installed; apps only display it.
  • 400The body is not a JSON object with string username and password. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No such player password, or it belongs to someone else. Body: string (text/plain)
  • 403The patron must enroll a second factor first. Body: string (text/plain)
  • 413The body is over 4 KiB. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/login' \
    -X POST \
    -H 'Content-Type: application/json' \
    -d '{"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/login' `
    -Method Post `
    -ContentType 'application/json' `
    -Body '{"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/login",
    json={"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/login", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/login")
    .json(&serde_json::json!({"username": "riley", "password": "ABCDE-FGHJK-LMNPQ-RSTUV"}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The patron, the card's tokens and settings.

{
  "user": {
    "id": "li_8f14e45fceea467f",
    "username": "riley",
    "email": "riley@example.com",
    "type": "user",
    "token": "eyJhbGciOi...",
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "isOldToken": false,
    "mediaProgress": [
      {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      }
    ],
    "seriesHideFromContinueListening": [],
    "bookmarks": [
      {
        "libraryItemId": "li_8f14e45fceea467f",
        "title": "The First",
        "time": 1830.0,
        "createdAt": 1763600000000
      }
    ],
    "isActive": true,
    "isLocked": false,
    "lastSeen": 1763630000000,
    "createdAt": 1763600000000,
    "permissions": {
      "download": true,
      "update": false,
      "delete": false,
      "upload": false,
      "createEreader": false,
      "accessAllLibraries": true,
      "accessAllTags": true,
      "accessExplicitContent": true,
      "selectedTagsNotAccessible": false
    },
    "librariesAccessible": [
      "bookclerk-library"
    ],
    "itemTagsSelected": [],
    "hasOpenIDLink": false
  },
  "userDefaultLibraryId": "bookclerk-library",
  "serverSettings": {
    "id": "li_8f14e45fceea467f",
    "version": "2.17.0",
    "buildNumber": 1,
    "language": "en-us",
    "dateFormat": "MM/dd/yyyy",
    "timeFormat": "HH:mm",
    "sortingIgnorePrefix": true,
    "sortingPrefixes": [
      "the",
      "a"
    ],
    "chromecastEnabled": false,
    "homeBookshelfView": 1,
    "bookshelfView": 1,
    "authActiveAuthMethods": [
      "local",
      "openid"
    ],
    "authOpenIDButtonText": "Sign in with the library",
    "authOpenIDAutoLaunch": false,
    "authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
    "timeZone": "UTC"
  },
  "ereaderDevices": [],
  "Source": "bookclerk"
}

Schema:

{
  "type": "object",
  "description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
  "required": [
    "user",
    "userDefaultLibraryId",
    "serverSettings",
    "ereaderDevices",
    "Source"
  ],
  "properties": {
    "user": {
      "type": "object",
      "description": "The signed-in patron, with the card's tokens.",
      "required": [
        "id",
        "username",
        "type",
        "token",
        "isOldToken",
        "mediaProgress",
        "seriesHideFromContinueListening",
        "bookmarks",
        "isActive",
        "isLocked",
        "createdAt",
        "permissions",
        "librariesAccessible",
        "itemTagsSelected",
        "hasOpenIDLink"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The patron's portal identity id, as a string.",
          "example": "li_8f14e45fceea467f"
        },
        "username": {
          "type": "string",
          "description": "The name the patron signs in with.",
          "example": "riley"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The patron's email address, if the library has one.",
          "example": "riley@example.com"
        },
        "type": {
          "type": "string",
          "description": "Always `user`: no app is given administrator powers.",
          "example": "user"
        },
        "token": {
          "type": "string",
          "description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
          "example": "eyJhbGciOi..."
        },
        "accessToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's access token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "refreshToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's refresh token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "isOldToken": {
          "type": "boolean",
          "description": "Always false: tokens are never the old non-expiring kind.",
          "example": false
        },
        "mediaProgress": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "The patron's progress on one item.",
            "required": [
              "id",
              "userId",
              "libraryItemId",
              "mediaItemId",
              "mediaItemType",
              "duration",
              "progress",
              "currentTime",
              "isFinished",
              "hideFromContinueListening",
              "lastUpdate",
              "startedAt"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The progress id: the item id (one record per patron and item).",
                "example": "li_8f14e45fceea467f"
              },
              "userId": {
                "type": "string",
                "description": "The patron's id.",
                "example": "42"
              },
              "libraryItemId": {
                "type": "string",
                "description": "The item id.",
                "example": "li_8f14e45fceea467f"
              },
              "episodeId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "mediaItemId": {
                "type": "string",
                "description": "The media id: the item id.",
                "example": "li_8f14e45fceea467f"
              },
              "mediaItemType": {
                "type": "string",
                "description": "Always `book`.",
                "example": "book"
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds, as last reported.",
                "example": 36000.0
              },
              "progress": {
                "type": "number",
                "format": "double",
                "description": "The share listened, from 0 to 1.",
                "example": 0.05
              },
              "currentTime": {
                "type": "number",
                "format": "double",
                "description": "Where the patron is, in seconds.",
                "example": 1830.5
              },
              "isFinished": {
                "type": "boolean",
                "description": "Whether the patron finished it.",
                "example": false
              },
              "hideFromContinueListening": {
                "type": "boolean",
                "description": "Whether it is hidden from continue listening.",
                "example": false
              },
              "ebookLocation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "ebookProgress": {
                "type": [
                  "number",
                  "null"
                ],
                "format": "double",
                "description": "Always null.",
                "example": null
              },
              "lastUpdate": {
                "type": "integer",
                "format": "int64",
                "description": "When the progress last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "startedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the patron started, in epoch milliseconds.",
                "example": 1763620000000
              },
              "finishedAt": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "When the patron finished, in epoch milliseconds.",
                "example": null
              }
            }
          },
          "description": "Progress on every item the patron has started."
        },
        "seriesHideFromContinueListening": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Series hidden from continue listening: none.",
          "example": []
        },
        "bookmarks": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A bookmark.",
            "required": [
              "libraryItemId",
              "title",
              "time",
              "createdAt"
            ],
            "properties": {
              "libraryItemId": {
                "type": "string",
                "description": "The item it is in.",
                "example": "li_8f14e45fceea467f"
              },
              "title": {
                "type": "string",
                "description": "Its title.",
                "example": "The First"
              },
              "time": {
                "type": "number",
                "format": "double",
                "description": "Where it is, in seconds.",
                "example": 1830.0
              },
              "createdAt": {
                "type": "integer",
                "format": "int64",
                "description": "When it was made, in epoch milliseconds.",
                "example": 1763600000000
              }
            }
          },
          "description": "Every bookmark the patron has made."
        },
        "isActive": {
          "type": "boolean",
          "description": "Always true: a disabled patron cannot sign in.",
          "example": true
        },
        "isLocked": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "lastSeen": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "When the patron was last seen, in epoch milliseconds.",
          "example": 1763630000000
        },
        "createdAt": {
          "type": "integer",
          "format": "int64",
          "description": "When the patron joined, in epoch milliseconds.",
          "example": 1763600000000
        },
        "permissions": {
          "type": "object",
          "description": "What the patron may do.",
          "required": [
            "download",
            "update",
            "delete",
            "upload",
            "createEreader",
            "accessAllLibraries",
            "accessAllTags",
            "accessExplicitContent",
            "selectedTagsNotAccessible"
          ],
          "properties": {
            "download": {
              "type": "boolean",
              "description": "Whether the patron may download items to the device.",
              "example": true
            },
            "update": {
              "type": "boolean",
              "description": "Always false: apps edit nothing.",
              "example": false
            },
            "delete": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "upload": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "createEreader": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "accessAllLibraries": {
              "type": "boolean",
              "description": "Always true: the libraries listed are the ones the patron sees.",
              "example": true
            },
            "accessAllTags": {
              "type": "boolean",
              "description": "Always true.",
              "example": true
            },
            "accessExplicitContent": {
              "type": "boolean",
              "description": "Always true: scope, not an explicit flag, decides visibility.",
              "example": true
            },
            "selectedTagsNotAccessible": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            }
          }
        },
        "librariesAccessible": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Libraries the patron may open, by id.",
          "example": [
            "bookclerk-library"
          ]
        },
        "itemTagsSelected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
          "example": []
        },
        "hasOpenIDLink": {
          "type": "boolean",
          "description": "Whether the patron signed in through the browser at least once.",
          "example": false
        }
      }
    },
    "userDefaultLibraryId": {
      "type": "string",
      "description": "The library an app opens first: the whole library.",
      "example": "bookclerk-library"
    },
    "serverSettings": {
      "type": "object",
      "description": "Settings apps read at sign-in.",
      "required": [
        "id",
        "version",
        "buildNumber",
        "language",
        "dateFormat",
        "timeFormat",
        "sortingIgnorePrefix",
        "sortingPrefixes",
        "chromecastEnabled",
        "homeBookshelfView",
        "bookshelfView",
        "authActiveAuthMethods",
        "authOpenIDButtonText",
        "authOpenIDAutoLaunch",
        "timeZone"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Always `server-settings`.",
          "example": "li_8f14e45fceea467f"
        },
        "version": {
          "type": "string",
          "description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
          "example": "2.17.0"
        },
        "buildNumber": {
          "type": "integer",
          "format": "int32",
          "description": "Always 1.",
          "example": 1,
          "minimum": 0
        },
        "language": {
          "type": "string",
          "description": "The interface language.",
          "example": "en-us"
        },
        "dateFormat": {
          "type": "string",
          "description": "How apps format dates.",
          "example": "MM/dd/yyyy"
        },
        "timeFormat": {
          "type": "string",
          "description": "How apps format times.",
          "example": "HH:mm"
        },
        "sortingIgnorePrefix": {
          "type": "boolean",
          "description": "Whether sorting skips leading articles: no.",
          "example": true
        },
        "sortingPrefixes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The articles sorting would skip.",
          "example": [
            "the",
            "a"
          ]
        },
        "chromecastEnabled": {
          "type": "boolean",
          "description": "Whether apps offer casting: no.",
          "example": false
        },
        "homeBookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The home shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "bookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The library shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "authActiveAuthMethods": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "[`AUTH_METHODS`].",
          "example": [
            "local",
            "openid"
          ]
        },
        "authOpenIDButtonText": {
          "type": "string",
          "description": "The browser sign-in button's label.",
          "example": "Sign in with the library"
        },
        "authOpenIDAutoLaunch": {
          "type": "boolean",
          "description": "Never true.",
          "example": false
        },
        "authLoginCustomMessage": {
          "type": [
            "string",
            "null"
          ],
          "description": "The sign-in screen's note.",
          "example": "Sign in with a player password from Settings, Account, Player apps."
        },
        "timeZone": {
          "type": "string",
          "description": "The host's time zone name, or UTC.",
          "example": "UTC"
        }
      }
    },
    "ereaderDevices": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "E-reader devices: always empty, the API serves no ebooks.",
      "example": []
    },
    "Source": {
      "type": "string",
      "description": "How the server was installed; apps only display it.",
      "example": "bookclerk"
    }
  }
}

Status 400: The body is not a JSON object with string username and password. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No such player password, or it belongs to someone else.

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor first.

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 413: The body is over 4 KiB.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `username` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

Internal Server Error

Schema:

A text/plain body: a string.

POST /player/auth/refresh

Trades a refresh token for a new access and refresh token.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • x-refresh-tokenheaderstringrequiredThe card's refresh token.

Responses

  • 200The patron and the card's new tokens. Body: PlayerLoginResponse (application/json)5 fields
    • userUserrequiredThe signed-in patron, with the card's tokens.
    • userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.
    • serverSettingsServerSettingsrequiredSettings apps read at sign-in.
    • ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.
    • SourcestringrequiredHow the server was installed; apps only display it.
  • 401No such live refresh token. Body: string (text/plain)
  • 403The patron must enroll a second factor first. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/auth/refresh' \
    -X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/refresh' `
    -Method Post
import requests

response = requests.post("http://127.0.0.1:8787/player/auth/refresh")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/refresh", {
  method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/auth/refresh")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The patron and the card's new tokens.

{
  "user": {
    "id": "li_8f14e45fceea467f",
    "username": "riley",
    "email": "riley@example.com",
    "type": "user",
    "token": "eyJhbGciOi...",
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "isOldToken": false,
    "mediaProgress": [
      {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      }
    ],
    "seriesHideFromContinueListening": [],
    "bookmarks": [
      {
        "libraryItemId": "li_8f14e45fceea467f",
        "title": "The First",
        "time": 1830.0,
        "createdAt": 1763600000000
      }
    ],
    "isActive": true,
    "isLocked": false,
    "lastSeen": 1763630000000,
    "createdAt": 1763600000000,
    "permissions": {
      "download": true,
      "update": false,
      "delete": false,
      "upload": false,
      "createEreader": false,
      "accessAllLibraries": true,
      "accessAllTags": true,
      "accessExplicitContent": true,
      "selectedTagsNotAccessible": false
    },
    "librariesAccessible": [
      "bookclerk-library"
    ],
    "itemTagsSelected": [],
    "hasOpenIDLink": false
  },
  "userDefaultLibraryId": "bookclerk-library",
  "serverSettings": {
    "id": "li_8f14e45fceea467f",
    "version": "2.17.0",
    "buildNumber": 1,
    "language": "en-us",
    "dateFormat": "MM/dd/yyyy",
    "timeFormat": "HH:mm",
    "sortingIgnorePrefix": true,
    "sortingPrefixes": [
      "the",
      "a"
    ],
    "chromecastEnabled": false,
    "homeBookshelfView": 1,
    "bookshelfView": 1,
    "authActiveAuthMethods": [
      "local",
      "openid"
    ],
    "authOpenIDButtonText": "Sign in with the library",
    "authOpenIDAutoLaunch": false,
    "authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
    "timeZone": "UTC"
  },
  "ereaderDevices": [],
  "Source": "bookclerk"
}

Schema:

{
  "type": "object",
  "description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
  "required": [
    "user",
    "userDefaultLibraryId",
    "serverSettings",
    "ereaderDevices",
    "Source"
  ],
  "properties": {
    "user": {
      "type": "object",
      "description": "The signed-in patron, with the card's tokens.",
      "required": [
        "id",
        "username",
        "type",
        "token",
        "isOldToken",
        "mediaProgress",
        "seriesHideFromContinueListening",
        "bookmarks",
        "isActive",
        "isLocked",
        "createdAt",
        "permissions",
        "librariesAccessible",
        "itemTagsSelected",
        "hasOpenIDLink"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The patron's portal identity id, as a string.",
          "example": "li_8f14e45fceea467f"
        },
        "username": {
          "type": "string",
          "description": "The name the patron signs in with.",
          "example": "riley"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The patron's email address, if the library has one.",
          "example": "riley@example.com"
        },
        "type": {
          "type": "string",
          "description": "Always `user`: no app is given administrator powers.",
          "example": "user"
        },
        "token": {
          "type": "string",
          "description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
          "example": "eyJhbGciOi..."
        },
        "accessToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's access token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "refreshToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's refresh token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "isOldToken": {
          "type": "boolean",
          "description": "Always false: tokens are never the old non-expiring kind.",
          "example": false
        },
        "mediaProgress": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "The patron's progress on one item.",
            "required": [
              "id",
              "userId",
              "libraryItemId",
              "mediaItemId",
              "mediaItemType",
              "duration",
              "progress",
              "currentTime",
              "isFinished",
              "hideFromContinueListening",
              "lastUpdate",
              "startedAt"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The progress id: the item id (one record per patron and item).",
                "example": "li_8f14e45fceea467f"
              },
              "userId": {
                "type": "string",
                "description": "The patron's id.",
                "example": "42"
              },
              "libraryItemId": {
                "type": "string",
                "description": "The item id.",
                "example": "li_8f14e45fceea467f"
              },
              "episodeId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "mediaItemId": {
                "type": "string",
                "description": "The media id: the item id.",
                "example": "li_8f14e45fceea467f"
              },
              "mediaItemType": {
                "type": "string",
                "description": "Always `book`.",
                "example": "book"
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds, as last reported.",
                "example": 36000.0
              },
              "progress": {
                "type": "number",
                "format": "double",
                "description": "The share listened, from 0 to 1.",
                "example": 0.05
              },
              "currentTime": {
                "type": "number",
                "format": "double",
                "description": "Where the patron is, in seconds.",
                "example": 1830.5
              },
              "isFinished": {
                "type": "boolean",
                "description": "Whether the patron finished it.",
                "example": false
              },
              "hideFromContinueListening": {
                "type": "boolean",
                "description": "Whether it is hidden from continue listening.",
                "example": false
              },
              "ebookLocation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "ebookProgress": {
                "type": [
                  "number",
                  "null"
                ],
                "format": "double",
                "description": "Always null.",
                "example": null
              },
              "lastUpdate": {
                "type": "integer",
                "format": "int64",
                "description": "When the progress last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "startedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the patron started, in epoch milliseconds.",
                "example": 1763620000000
              },
              "finishedAt": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "When the patron finished, in epoch milliseconds.",
                "example": null
              }
            }
          },
          "description": "Progress on every item the patron has started."
        },
        "seriesHideFromContinueListening": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Series hidden from continue listening: none.",
          "example": []
        },
        "bookmarks": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A bookmark.",
            "required": [
              "libraryItemId",
              "title",
              "time",
              "createdAt"
            ],
            "properties": {
              "libraryItemId": {
                "type": "string",
                "description": "The item it is in.",
                "example": "li_8f14e45fceea467f"
              },
              "title": {
                "type": "string",
                "description": "Its title.",
                "example": "The First"
              },
              "time": {
                "type": "number",
                "format": "double",
                "description": "Where it is, in seconds.",
                "example": 1830.0
              },
              "createdAt": {
                "type": "integer",
                "format": "int64",
                "description": "When it was made, in epoch milliseconds.",
                "example": 1763600000000
              }
            }
          },
          "description": "Every bookmark the patron has made."
        },
        "isActive": {
          "type": "boolean",
          "description": "Always true: a disabled patron cannot sign in.",
          "example": true
        },
        "isLocked": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "lastSeen": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "When the patron was last seen, in epoch milliseconds.",
          "example": 1763630000000
        },
        "createdAt": {
          "type": "integer",
          "format": "int64",
          "description": "When the patron joined, in epoch milliseconds.",
          "example": 1763600000000
        },
        "permissions": {
          "type": "object",
          "description": "What the patron may do.",
          "required": [
            "download",
            "update",
            "delete",
            "upload",
            "createEreader",
            "accessAllLibraries",
            "accessAllTags",
            "accessExplicitContent",
            "selectedTagsNotAccessible"
          ],
          "properties": {
            "download": {
              "type": "boolean",
              "description": "Whether the patron may download items to the device.",
              "example": true
            },
            "update": {
              "type": "boolean",
              "description": "Always false: apps edit nothing.",
              "example": false
            },
            "delete": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "upload": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "createEreader": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "accessAllLibraries": {
              "type": "boolean",
              "description": "Always true: the libraries listed are the ones the patron sees.",
              "example": true
            },
            "accessAllTags": {
              "type": "boolean",
              "description": "Always true.",
              "example": true
            },
            "accessExplicitContent": {
              "type": "boolean",
              "description": "Always true: scope, not an explicit flag, decides visibility.",
              "example": true
            },
            "selectedTagsNotAccessible": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            }
          }
        },
        "librariesAccessible": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Libraries the patron may open, by id.",
          "example": [
            "bookclerk-library"
          ]
        },
        "itemTagsSelected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
          "example": []
        },
        "hasOpenIDLink": {
          "type": "boolean",
          "description": "Whether the patron signed in through the browser at least once.",
          "example": false
        }
      }
    },
    "userDefaultLibraryId": {
      "type": "string",
      "description": "The library an app opens first: the whole library.",
      "example": "bookclerk-library"
    },
    "serverSettings": {
      "type": "object",
      "description": "Settings apps read at sign-in.",
      "required": [
        "id",
        "version",
        "buildNumber",
        "language",
        "dateFormat",
        "timeFormat",
        "sortingIgnorePrefix",
        "sortingPrefixes",
        "chromecastEnabled",
        "homeBookshelfView",
        "bookshelfView",
        "authActiveAuthMethods",
        "authOpenIDButtonText",
        "authOpenIDAutoLaunch",
        "timeZone"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Always `server-settings`.",
          "example": "li_8f14e45fceea467f"
        },
        "version": {
          "type": "string",
          "description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
          "example": "2.17.0"
        },
        "buildNumber": {
          "type": "integer",
          "format": "int32",
          "description": "Always 1.",
          "example": 1,
          "minimum": 0
        },
        "language": {
          "type": "string",
          "description": "The interface language.",
          "example": "en-us"
        },
        "dateFormat": {
          "type": "string",
          "description": "How apps format dates.",
          "example": "MM/dd/yyyy"
        },
        "timeFormat": {
          "type": "string",
          "description": "How apps format times.",
          "example": "HH:mm"
        },
        "sortingIgnorePrefix": {
          "type": "boolean",
          "description": "Whether sorting skips leading articles: no.",
          "example": true
        },
        "sortingPrefixes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The articles sorting would skip.",
          "example": [
            "the",
            "a"
          ]
        },
        "chromecastEnabled": {
          "type": "boolean",
          "description": "Whether apps offer casting: no.",
          "example": false
        },
        "homeBookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The home shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "bookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The library shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "authActiveAuthMethods": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "[`AUTH_METHODS`].",
          "example": [
            "local",
            "openid"
          ]
        },
        "authOpenIDButtonText": {
          "type": "string",
          "description": "The browser sign-in button's label.",
          "example": "Sign in with the library"
        },
        "authOpenIDAutoLaunch": {
          "type": "boolean",
          "description": "Never true.",
          "example": false
        },
        "authLoginCustomMessage": {
          "type": [
            "string",
            "null"
          ],
          "description": "The sign-in screen's note.",
          "example": "Sign in with a player password from Settings, Account, Player apps."
        },
        "timeZone": {
          "type": "string",
          "description": "The host's time zone name, or UTC.",
          "example": "UTC"
        }
      }
    },
    "ereaderDevices": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "E-reader devices: always empty, the API serves no ebooks.",
      "example": []
    },
    "Source": {
      "type": "string",
      "description": "How the server was installed; apps only display it.",
      "example": "bookclerk"
    }
  }
}

Status 401: No such live refresh token.

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor first.

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

Internal Server Error

Schema:

A text/plain body: a string.

POST /player/logout

Ends the card a refresh token (or the bearer access token) belongs to.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • x-refresh-tokenheaderstring or nullThe card's refresh token; without it, the bearer access token names the card.

Responses

  • 200OK, whether or not a card was live. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/logout' \
    -X POST
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/logout' `
    -Method Post
import requests

response = requests.post("http://127.0.0.1:8787/player/logout")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/logout", {
  method: "POST",
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/logout")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK, whether or not a card was live.

string

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

GET /player/auth/openid

Starts the browser sign-in: answers a 302 to the library's consent page, which the app opens in a browser.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • code_challengequerystringrequiredPKCE S256 challenge.
  • code_challenge_methodquerystringrequiredS256.
  • redirect_uriquerystringrequiredThe app's address: audiobookshelf://oauth, absorb://oauth or lissen://oauth.
  • client_idquerystringThe app's own name; echoed.
  • response_typequerystringcode.
  • statequerystringHanded back to the app with the code.

Responses

  • 302Location is the consent page, with the parameters the app passes on. No body.
  • 400A parameter is missing or malformed, or the app is not one the library returns to (Invalid redirect_uri). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string'
import requests

response = requests.get("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid?code_challenge=string&code_challenge_method=string&redirect_uri=string").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 302: Location is the consent page, with the parameters the app passes on. No body.

Status 400: A parameter is missing or malformed, or the app is not one the library returns to (Invalid redirect_uri).

Bad Request

Schema:

A text/plain body: a string.

GET /player/auth/openid/mobile-redirect

Sends the browser back to the app with the code (or the refusal).

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • appquerystringrequiredThe app's address, one the library returns to.
  • codequerystringThe code; absent when the patron declined.
  • statequerystringThe app's state.

Responses

  • 302Location is the app's address with code and state (or error=access_denied). No body.
  • 400The app is not one the library returns to, or a parameter is malformed. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string'
import requests

response = requests.get("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid/mobile-redirect?app=string").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 302: Location is the app's address with code and state (or error=access_denied). No body.

Status 400: The app is not one the library returns to, or a parameter is malformed.

Bad Request

Schema:

A text/plain body: a string.

GET /player/auth/openid/callback

Trades a browser sign-in's code and PKCE verifier for a card.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • codequerystringrequiredThe code the app was handed.
  • code_verifierquerystringrequiredThe PKCE verifier.
  • statequerystringThe app's state; not read.

Responses

  • 200The patron, the card's tokens and settings. Body: PlayerLoginResponse (application/json)5 fields
    • userUserrequiredThe signed-in patron, with the card's tokens.
    • userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.
    • serverSettingsServerSettingsrequiredSettings apps read at sign-in.
    • ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.
    • SourcestringrequiredHow the server was installed; apps only display it.
  • 400The code or verifier is missing or malformed. Body: string (text/plain)
  • 401The code is unknown, spent, expired, or does not match the verifier. Body: string (text/plain)
  • 403The patron must enroll a second factor first. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string'
import requests

response = requests.get("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/auth/openid/callback?code=string&code_verifier=string").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The patron, the card's tokens and settings.

{
  "user": {
    "id": "li_8f14e45fceea467f",
    "username": "riley",
    "email": "riley@example.com",
    "type": "user",
    "token": "eyJhbGciOi...",
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "isOldToken": false,
    "mediaProgress": [
      {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      }
    ],
    "seriesHideFromContinueListening": [],
    "bookmarks": [
      {
        "libraryItemId": "li_8f14e45fceea467f",
        "title": "The First",
        "time": 1830.0,
        "createdAt": 1763600000000
      }
    ],
    "isActive": true,
    "isLocked": false,
    "lastSeen": 1763630000000,
    "createdAt": 1763600000000,
    "permissions": {
      "download": true,
      "update": false,
      "delete": false,
      "upload": false,
      "createEreader": false,
      "accessAllLibraries": true,
      "accessAllTags": true,
      "accessExplicitContent": true,
      "selectedTagsNotAccessible": false
    },
    "librariesAccessible": [
      "bookclerk-library"
    ],
    "itemTagsSelected": [],
    "hasOpenIDLink": false
  },
  "userDefaultLibraryId": "bookclerk-library",
  "serverSettings": {
    "id": "li_8f14e45fceea467f",
    "version": "2.17.0",
    "buildNumber": 1,
    "language": "en-us",
    "dateFormat": "MM/dd/yyyy",
    "timeFormat": "HH:mm",
    "sortingIgnorePrefix": true,
    "sortingPrefixes": [
      "the",
      "a"
    ],
    "chromecastEnabled": false,
    "homeBookshelfView": 1,
    "bookshelfView": 1,
    "authActiveAuthMethods": [
      "local",
      "openid"
    ],
    "authOpenIDButtonText": "Sign in with the library",
    "authOpenIDAutoLaunch": false,
    "authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
    "timeZone": "UTC"
  },
  "ereaderDevices": [],
  "Source": "bookclerk"
}

Schema:

{
  "type": "object",
  "description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
  "required": [
    "user",
    "userDefaultLibraryId",
    "serverSettings",
    "ereaderDevices",
    "Source"
  ],
  "properties": {
    "user": {
      "type": "object",
      "description": "The signed-in patron, with the card's tokens.",
      "required": [
        "id",
        "username",
        "type",
        "token",
        "isOldToken",
        "mediaProgress",
        "seriesHideFromContinueListening",
        "bookmarks",
        "isActive",
        "isLocked",
        "createdAt",
        "permissions",
        "librariesAccessible",
        "itemTagsSelected",
        "hasOpenIDLink"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The patron's portal identity id, as a string.",
          "example": "li_8f14e45fceea467f"
        },
        "username": {
          "type": "string",
          "description": "The name the patron signs in with.",
          "example": "riley"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The patron's email address, if the library has one.",
          "example": "riley@example.com"
        },
        "type": {
          "type": "string",
          "description": "Always `user`: no app is given administrator powers.",
          "example": "user"
        },
        "token": {
          "type": "string",
          "description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
          "example": "eyJhbGciOi..."
        },
        "accessToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's access token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "refreshToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's refresh token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "isOldToken": {
          "type": "boolean",
          "description": "Always false: tokens are never the old non-expiring kind.",
          "example": false
        },
        "mediaProgress": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "The patron's progress on one item.",
            "required": [
              "id",
              "userId",
              "libraryItemId",
              "mediaItemId",
              "mediaItemType",
              "duration",
              "progress",
              "currentTime",
              "isFinished",
              "hideFromContinueListening",
              "lastUpdate",
              "startedAt"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The progress id: the item id (one record per patron and item).",
                "example": "li_8f14e45fceea467f"
              },
              "userId": {
                "type": "string",
                "description": "The patron's id.",
                "example": "42"
              },
              "libraryItemId": {
                "type": "string",
                "description": "The item id.",
                "example": "li_8f14e45fceea467f"
              },
              "episodeId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "mediaItemId": {
                "type": "string",
                "description": "The media id: the item id.",
                "example": "li_8f14e45fceea467f"
              },
              "mediaItemType": {
                "type": "string",
                "description": "Always `book`.",
                "example": "book"
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds, as last reported.",
                "example": 36000.0
              },
              "progress": {
                "type": "number",
                "format": "double",
                "description": "The share listened, from 0 to 1.",
                "example": 0.05
              },
              "currentTime": {
                "type": "number",
                "format": "double",
                "description": "Where the patron is, in seconds.",
                "example": 1830.5
              },
              "isFinished": {
                "type": "boolean",
                "description": "Whether the patron finished it.",
                "example": false
              },
              "hideFromContinueListening": {
                "type": "boolean",
                "description": "Whether it is hidden from continue listening.",
                "example": false
              },
              "ebookLocation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "ebookProgress": {
                "type": [
                  "number",
                  "null"
                ],
                "format": "double",
                "description": "Always null.",
                "example": null
              },
              "lastUpdate": {
                "type": "integer",
                "format": "int64",
                "description": "When the progress last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "startedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the patron started, in epoch milliseconds.",
                "example": 1763620000000
              },
              "finishedAt": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "When the patron finished, in epoch milliseconds.",
                "example": null
              }
            }
          },
          "description": "Progress on every item the patron has started."
        },
        "seriesHideFromContinueListening": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Series hidden from continue listening: none.",
          "example": []
        },
        "bookmarks": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A bookmark.",
            "required": [
              "libraryItemId",
              "title",
              "time",
              "createdAt"
            ],
            "properties": {
              "libraryItemId": {
                "type": "string",
                "description": "The item it is in.",
                "example": "li_8f14e45fceea467f"
              },
              "title": {
                "type": "string",
                "description": "Its title.",
                "example": "The First"
              },
              "time": {
                "type": "number",
                "format": "double",
                "description": "Where it is, in seconds.",
                "example": 1830.0
              },
              "createdAt": {
                "type": "integer",
                "format": "int64",
                "description": "When it was made, in epoch milliseconds.",
                "example": 1763600000000
              }
            }
          },
          "description": "Every bookmark the patron has made."
        },
        "isActive": {
          "type": "boolean",
          "description": "Always true: a disabled patron cannot sign in.",
          "example": true
        },
        "isLocked": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "lastSeen": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "When the patron was last seen, in epoch milliseconds.",
          "example": 1763630000000
        },
        "createdAt": {
          "type": "integer",
          "format": "int64",
          "description": "When the patron joined, in epoch milliseconds.",
          "example": 1763600000000
        },
        "permissions": {
          "type": "object",
          "description": "What the patron may do.",
          "required": [
            "download",
            "update",
            "delete",
            "upload",
            "createEreader",
            "accessAllLibraries",
            "accessAllTags",
            "accessExplicitContent",
            "selectedTagsNotAccessible"
          ],
          "properties": {
            "download": {
              "type": "boolean",
              "description": "Whether the patron may download items to the device.",
              "example": true
            },
            "update": {
              "type": "boolean",
              "description": "Always false: apps edit nothing.",
              "example": false
            },
            "delete": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "upload": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "createEreader": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "accessAllLibraries": {
              "type": "boolean",
              "description": "Always true: the libraries listed are the ones the patron sees.",
              "example": true
            },
            "accessAllTags": {
              "type": "boolean",
              "description": "Always true.",
              "example": true
            },
            "accessExplicitContent": {
              "type": "boolean",
              "description": "Always true: scope, not an explicit flag, decides visibility.",
              "example": true
            },
            "selectedTagsNotAccessible": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            }
          }
        },
        "librariesAccessible": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Libraries the patron may open, by id.",
          "example": [
            "bookclerk-library"
          ]
        },
        "itemTagsSelected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
          "example": []
        },
        "hasOpenIDLink": {
          "type": "boolean",
          "description": "Whether the patron signed in through the browser at least once.",
          "example": false
        }
      }
    },
    "userDefaultLibraryId": {
      "type": "string",
      "description": "The library an app opens first: the whole library.",
      "example": "bookclerk-library"
    },
    "serverSettings": {
      "type": "object",
      "description": "Settings apps read at sign-in.",
      "required": [
        "id",
        "version",
        "buildNumber",
        "language",
        "dateFormat",
        "timeFormat",
        "sortingIgnorePrefix",
        "sortingPrefixes",
        "chromecastEnabled",
        "homeBookshelfView",
        "bookshelfView",
        "authActiveAuthMethods",
        "authOpenIDButtonText",
        "authOpenIDAutoLaunch",
        "timeZone"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Always `server-settings`.",
          "example": "li_8f14e45fceea467f"
        },
        "version": {
          "type": "string",
          "description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
          "example": "2.17.0"
        },
        "buildNumber": {
          "type": "integer",
          "format": "int32",
          "description": "Always 1.",
          "example": 1,
          "minimum": 0
        },
        "language": {
          "type": "string",
          "description": "The interface language.",
          "example": "en-us"
        },
        "dateFormat": {
          "type": "string",
          "description": "How apps format dates.",
          "example": "MM/dd/yyyy"
        },
        "timeFormat": {
          "type": "string",
          "description": "How apps format times.",
          "example": "HH:mm"
        },
        "sortingIgnorePrefix": {
          "type": "boolean",
          "description": "Whether sorting skips leading articles: no.",
          "example": true
        },
        "sortingPrefixes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The articles sorting would skip.",
          "example": [
            "the",
            "a"
          ]
        },
        "chromecastEnabled": {
          "type": "boolean",
          "description": "Whether apps offer casting: no.",
          "example": false
        },
        "homeBookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The home shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "bookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The library shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "authActiveAuthMethods": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "[`AUTH_METHODS`].",
          "example": [
            "local",
            "openid"
          ]
        },
        "authOpenIDButtonText": {
          "type": "string",
          "description": "The browser sign-in button's label.",
          "example": "Sign in with the library"
        },
        "authOpenIDAutoLaunch": {
          "type": "boolean",
          "description": "Never true.",
          "example": false
        },
        "authLoginCustomMessage": {
          "type": [
            "string",
            "null"
          ],
          "description": "The sign-in screen's note.",
          "example": "Sign in with a player password from Settings, Account, Player apps."
        },
        "timeZone": {
          "type": "string",
          "description": "The host's time zone name, or UTC.",
          "example": "UTC"
        }
      }
    },
    "ereaderDevices": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "E-reader devices: always empty, the API serves no ebooks.",
      "example": []
    },
    "Source": {
      "type": "string",
      "description": "How the server was installed; apps only display it.",
      "example": "bookclerk"
    }
  }
}

Status 400: The code or verifier is missing or malformed.

Bad Request

Schema:

A text/plain body: a string.

Status 401: The code is unknown, spent, expired, or does not match the verifier.

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor first.

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

Internal Server Error

Schema:

A text/plain body: a string.

GET /player/socket.io/

Opens the live socket.

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • EIOquerystringrequired4.
  • transportquerystringrequiredwebsocket; long polling is not served.

Responses

  • 101Switching to the Socket.IO websocket. No body.
  • 400Not a websocket upgrade, another Engine.IO revision, or long polling. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string'
import requests

response = requests.get("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/socket.io/?EIO=string&transport=string").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 101: Switching to the Socket.IO websocket. No body.

Status 400: Not a websocket upgrade, another Engine.IO revision, or long polling.

Bad Request

Schema:

A text/plain body: a string.

GET /player/socket.io

Opens the live socket for a client that drops the trailing slash; the same socket as [get_socket].

Access: No auth layer. Routes that need a caller say so in security; the handler checks it.

Credentials: none

Parameters

  • EIOquerystringrequired4.
  • transportquerystringrequiredwebsocket; long polling is not served.

Responses

  • 101Switching to the Socket.IO websocket. No body.
  • 400Not a websocket upgrade, another Engine.IO revision, or long polling. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string'
import requests

response = requests.get("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string")
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string");
console.log(response.status, await response.text());
let response = reqwest::get("http://127.0.0.1:8787/player/socket.io?EIO=string&transport=string").await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 101: Switching to the Socket.IO websocket. No body.

Status 400: Not a websocket upgrade, another Engine.IO revision, or long polling.

Bad Request

Schema:

A text/plain body: a string.

POST /player/api/authorize

The signed-in patron, as at sign-in, without new tokens.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Responses

  • 200The patron and settings; user.token is the card's access token. Body: PlayerLoginResponse (application/json)5 fields
    • userUserrequiredThe signed-in patron, with the card's tokens.
    • userDefaultLibraryIdstringrequiredThe library an app opens first: the whole library.
    • serverSettingsServerSettingsrequiredSettings apps read at sign-in.
    • ereaderDevicesarray of objectrequiredE-reader devices: always empty, the API serves no ebooks.
    • SourcestringrequiredHow the server was installed; apps only display it.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/authorize' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/authorize' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/authorize",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/authorize", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/authorize")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The patron and settings; user.token is the card's access token.

{
  "user": {
    "id": "li_8f14e45fceea467f",
    "username": "riley",
    "email": "riley@example.com",
    "type": "user",
    "token": "eyJhbGciOi...",
    "accessToken": "eyJhbGciOi...",
    "refreshToken": "eyJhbGciOi...",
    "isOldToken": false,
    "mediaProgress": [
      {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      }
    ],
    "seriesHideFromContinueListening": [],
    "bookmarks": [
      {
        "libraryItemId": "li_8f14e45fceea467f",
        "title": "The First",
        "time": 1830.0,
        "createdAt": 1763600000000
      }
    ],
    "isActive": true,
    "isLocked": false,
    "lastSeen": 1763630000000,
    "createdAt": 1763600000000,
    "permissions": {
      "download": true,
      "update": false,
      "delete": false,
      "upload": false,
      "createEreader": false,
      "accessAllLibraries": true,
      "accessAllTags": true,
      "accessExplicitContent": true,
      "selectedTagsNotAccessible": false
    },
    "librariesAccessible": [
      "bookclerk-library"
    ],
    "itemTagsSelected": [],
    "hasOpenIDLink": false
  },
  "userDefaultLibraryId": "bookclerk-library",
  "serverSettings": {
    "id": "li_8f14e45fceea467f",
    "version": "2.17.0",
    "buildNumber": 1,
    "language": "en-us",
    "dateFormat": "MM/dd/yyyy",
    "timeFormat": "HH:mm",
    "sortingIgnorePrefix": true,
    "sortingPrefixes": [
      "the",
      "a"
    ],
    "chromecastEnabled": false,
    "homeBookshelfView": 1,
    "bookshelfView": 1,
    "authActiveAuthMethods": [
      "local",
      "openid"
    ],
    "authOpenIDButtonText": "Sign in with the library",
    "authOpenIDAutoLaunch": false,
    "authLoginCustomMessage": "Sign in with a player password from Settings, Account, Player apps.",
    "timeZone": "UTC"
  },
  "ereaderDevices": [],
  "Source": "bookclerk"
}

Schema:

{
  "type": "object",
  "description": "The answer to a sign-in, a token refresh, `POST /api/authorize` and\nthe browser sign-in's callback.",
  "required": [
    "user",
    "userDefaultLibraryId",
    "serverSettings",
    "ereaderDevices",
    "Source"
  ],
  "properties": {
    "user": {
      "type": "object",
      "description": "The signed-in patron, with the card's tokens.",
      "required": [
        "id",
        "username",
        "type",
        "token",
        "isOldToken",
        "mediaProgress",
        "seriesHideFromContinueListening",
        "bookmarks",
        "isActive",
        "isLocked",
        "createdAt",
        "permissions",
        "librariesAccessible",
        "itemTagsSelected",
        "hasOpenIDLink"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The patron's portal identity id, as a string.",
          "example": "li_8f14e45fceea467f"
        },
        "username": {
          "type": "string",
          "description": "The name the patron signs in with.",
          "example": "riley"
        },
        "email": {
          "type": [
            "string",
            "null"
          ],
          "description": "The patron's email address, if the library has one.",
          "example": "riley@example.com"
        },
        "type": {
          "type": "string",
          "description": "Always `user`: no app is given administrator powers.",
          "example": "user"
        },
        "token": {
          "type": "string",
          "description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
          "example": "eyJhbGciOi..."
        },
        "accessToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's access token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "refreshToken": {
          "type": [
            "string",
            "null"
          ],
          "description": "The card's refresh token, on sign-in and refresh answers only.",
          "example": "eyJhbGciOi..."
        },
        "isOldToken": {
          "type": "boolean",
          "description": "Always false: tokens are never the old non-expiring kind.",
          "example": false
        },
        "mediaProgress": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "The patron's progress on one item.",
            "required": [
              "id",
              "userId",
              "libraryItemId",
              "mediaItemId",
              "mediaItemType",
              "duration",
              "progress",
              "currentTime",
              "isFinished",
              "hideFromContinueListening",
              "lastUpdate",
              "startedAt"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The progress id: the item id (one record per patron and item).",
                "example": "li_8f14e45fceea467f"
              },
              "userId": {
                "type": "string",
                "description": "The patron's id.",
                "example": "42"
              },
              "libraryItemId": {
                "type": "string",
                "description": "The item id.",
                "example": "li_8f14e45fceea467f"
              },
              "episodeId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "mediaItemId": {
                "type": "string",
                "description": "The media id: the item id.",
                "example": "li_8f14e45fceea467f"
              },
              "mediaItemType": {
                "type": "string",
                "description": "Always `book`.",
                "example": "book"
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds, as last reported.",
                "example": 36000.0
              },
              "progress": {
                "type": "number",
                "format": "double",
                "description": "The share listened, from 0 to 1.",
                "example": 0.05
              },
              "currentTime": {
                "type": "number",
                "format": "double",
                "description": "Where the patron is, in seconds.",
                "example": 1830.5
              },
              "isFinished": {
                "type": "boolean",
                "description": "Whether the patron finished it.",
                "example": false
              },
              "hideFromContinueListening": {
                "type": "boolean",
                "description": "Whether it is hidden from continue listening.",
                "example": false
              },
              "ebookLocation": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "ebookProgress": {
                "type": [
                  "number",
                  "null"
                ],
                "format": "double",
                "description": "Always null.",
                "example": null
              },
              "lastUpdate": {
                "type": "integer",
                "format": "int64",
                "description": "When the progress last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "startedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the patron started, in epoch milliseconds.",
                "example": 1763620000000
              },
              "finishedAt": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "When the patron finished, in epoch milliseconds.",
                "example": null
              }
            }
          },
          "description": "Progress on every item the patron has started."
        },
        "seriesHideFromContinueListening": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Series hidden from continue listening: none.",
          "example": []
        },
        "bookmarks": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A bookmark.",
            "required": [
              "libraryItemId",
              "title",
              "time",
              "createdAt"
            ],
            "properties": {
              "libraryItemId": {
                "type": "string",
                "description": "The item it is in.",
                "example": "li_8f14e45fceea467f"
              },
              "title": {
                "type": "string",
                "description": "Its title.",
                "example": "The First"
              },
              "time": {
                "type": "number",
                "format": "double",
                "description": "Where it is, in seconds.",
                "example": 1830.0
              },
              "createdAt": {
                "type": "integer",
                "format": "int64",
                "description": "When it was made, in epoch milliseconds.",
                "example": 1763600000000
              }
            }
          },
          "description": "Every bookmark the patron has made."
        },
        "isActive": {
          "type": "boolean",
          "description": "Always true: a disabled patron cannot sign in.",
          "example": true
        },
        "isLocked": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "lastSeen": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "When the patron was last seen, in epoch milliseconds.",
          "example": 1763630000000
        },
        "createdAt": {
          "type": "integer",
          "format": "int64",
          "description": "When the patron joined, in epoch milliseconds.",
          "example": 1763600000000
        },
        "permissions": {
          "type": "object",
          "description": "What the patron may do.",
          "required": [
            "download",
            "update",
            "delete",
            "upload",
            "createEreader",
            "accessAllLibraries",
            "accessAllTags",
            "accessExplicitContent",
            "selectedTagsNotAccessible"
          ],
          "properties": {
            "download": {
              "type": "boolean",
              "description": "Whether the patron may download items to the device.",
              "example": true
            },
            "update": {
              "type": "boolean",
              "description": "Always false: apps edit nothing.",
              "example": false
            },
            "delete": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "upload": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "createEreader": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "accessAllLibraries": {
              "type": "boolean",
              "description": "Always true: the libraries listed are the ones the patron sees.",
              "example": true
            },
            "accessAllTags": {
              "type": "boolean",
              "description": "Always true.",
              "example": true
            },
            "accessExplicitContent": {
              "type": "boolean",
              "description": "Always true: scope, not an explicit flag, decides visibility.",
              "example": true
            },
            "selectedTagsNotAccessible": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            }
          }
        },
        "librariesAccessible": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Libraries the patron may open, by id.",
          "example": [
            "bookclerk-library"
          ]
        },
        "itemTagsSelected": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
          "example": []
        },
        "hasOpenIDLink": {
          "type": "boolean",
          "description": "Whether the patron signed in through the browser at least once.",
          "example": false
        }
      }
    },
    "userDefaultLibraryId": {
      "type": "string",
      "description": "The library an app opens first: the whole library.",
      "example": "bookclerk-library"
    },
    "serverSettings": {
      "type": "object",
      "description": "Settings apps read at sign-in.",
      "required": [
        "id",
        "version",
        "buildNumber",
        "language",
        "dateFormat",
        "timeFormat",
        "sortingIgnorePrefix",
        "sortingPrefixes",
        "chromecastEnabled",
        "homeBookshelfView",
        "bookshelfView",
        "authActiveAuthMethods",
        "authOpenIDButtonText",
        "authOpenIDAutoLaunch",
        "timeZone"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "Always `server-settings`.",
          "example": "li_8f14e45fceea467f"
        },
        "version": {
          "type": "string",
          "description": "[`crate::COMPATIBLE_SERVER_VERSION`]: apps turn features on by it.",
          "example": "2.17.0"
        },
        "buildNumber": {
          "type": "integer",
          "format": "int32",
          "description": "Always 1.",
          "example": 1,
          "minimum": 0
        },
        "language": {
          "type": "string",
          "description": "The interface language.",
          "example": "en-us"
        },
        "dateFormat": {
          "type": "string",
          "description": "How apps format dates.",
          "example": "MM/dd/yyyy"
        },
        "timeFormat": {
          "type": "string",
          "description": "How apps format times.",
          "example": "HH:mm"
        },
        "sortingIgnorePrefix": {
          "type": "boolean",
          "description": "Whether sorting skips leading articles: no.",
          "example": true
        },
        "sortingPrefixes": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The articles sorting would skip.",
          "example": [
            "the",
            "a"
          ]
        },
        "chromecastEnabled": {
          "type": "boolean",
          "description": "Whether apps offer casting: no.",
          "example": false
        },
        "homeBookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The home shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "bookshelfView": {
          "type": "integer",
          "format": "int32",
          "description": "The library shelf style (1: standard).",
          "example": 1,
          "minimum": 0
        },
        "authActiveAuthMethods": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "[`AUTH_METHODS`].",
          "example": [
            "local",
            "openid"
          ]
        },
        "authOpenIDButtonText": {
          "type": "string",
          "description": "The browser sign-in button's label.",
          "example": "Sign in with the library"
        },
        "authOpenIDAutoLaunch": {
          "type": "boolean",
          "description": "Never true.",
          "example": false
        },
        "authLoginCustomMessage": {
          "type": [
            "string",
            "null"
          ],
          "description": "The sign-in screen's note.",
          "example": "Sign in with a player password from Settings, Account, Player apps."
        },
        "timeZone": {
          "type": "string",
          "description": "The host's time zone name, or UTC.",
          "example": "UTC"
        }
      }
    },
    "ereaderDevices": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "E-reader devices: always empty, the API serves no ebooks.",
      "example": []
    },
    "Source": {
      "type": "string",
      "description": "How the server was installed; apps only display it.",
      "example": "bookclerk"
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/me

The signed-in patron.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Responses

  • 200The patron, their progress and bookmarks. Body: User (application/json)19 fields
    • idstringrequiredThe patron's portal identity id, as a string.
    • usernamestringrequiredThe name the patron signs in with.
    • emailstring or nullThe patron's email address, if the library has one.
    • typestringrequiredAlways user: no app is given administrator powers.
    • tokenstringrequiredThe access token, for apps that read it from here (older apps send this one as their bearer). Empty where the answer is not a sign-in.
    • accessTokenstring or nullThe card's access token, on sign-in and refresh answers only.
    • refreshTokenstring or nullThe card's refresh token, on sign-in and refresh answers only.
    • isOldTokenbooleanrequiredAlways false: tokens are never the old non-expiring kind.
    • mediaProgressarray of MediaProgressrequiredProgress on every item the patron has started.
    • seriesHideFromContinueListeningarray of stringrequiredSeries hidden from continue listening: none.
    • bookmarksarray of BookmarkrequiredEvery bookmark the patron has made.
    • isActivebooleanrequiredAlways true: a disabled patron cannot sign in.
    • isLockedbooleanrequiredAlways false.
    • lastSeeninteger (int64) or nullWhen the patron was last seen, in epoch milliseconds.
    • createdAtinteger (int64)requiredWhen the patron joined, in epoch milliseconds.
    • permissionsPermissionsrequiredWhat the patron may do.
    • librariesAccessiblearray of stringrequiredLibraries the patron may open, by id.
    • itemTagsSelectedarray of stringrequiredTags that limit what the patron sees: none (scope is applied by the host, not by tags).
    • hasOpenIDLinkbooleanrequiredWhether the patron signed in through the browser at least once.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/me",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/me")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The patron, their progress and bookmarks.

{
  "id": "li_8f14e45fceea467f",
  "username": "riley",
  "email": "riley@example.com",
  "type": "user",
  "token": "eyJhbGciOi...",
  "accessToken": "eyJhbGciOi...",
  "refreshToken": "eyJhbGciOi...",
  "isOldToken": false,
  "mediaProgress": [
    {
      "id": "li_8f14e45fceea467f",
      "userId": "42",
      "libraryItemId": "li_8f14e45fceea467f",
      "episodeId": null,
      "mediaItemId": "li_8f14e45fceea467f",
      "mediaItemType": "book",
      "duration": 36000.0,
      "progress": 0.05,
      "currentTime": 1830.5,
      "isFinished": false,
      "hideFromContinueListening": false,
      "ebookLocation": null,
      "ebookProgress": null,
      "lastUpdate": 1763630000000,
      "startedAt": 1763620000000,
      "finishedAt": null
    }
  ],
  "seriesHideFromContinueListening": [],
  "bookmarks": [
    {
      "libraryItemId": "li_8f14e45fceea467f",
      "title": "The First",
      "time": 1830.0,
      "createdAt": 1763600000000
    }
  ],
  "isActive": true,
  "isLocked": false,
  "lastSeen": 1763630000000,
  "createdAt": 1763600000000,
  "permissions": {
    "download": true,
    "update": false,
    "delete": false,
    "upload": false,
    "createEreader": false,
    "accessAllLibraries": true,
    "accessAllTags": true,
    "accessExplicitContent": true,
    "selectedTagsNotAccessible": false
  },
  "librariesAccessible": [
    "bookclerk-library"
  ],
  "itemTagsSelected": [],
  "hasOpenIDLink": false
}

Schema:

{
  "type": "object",
  "description": "A patron as apps see them.",
  "required": [
    "id",
    "username",
    "type",
    "token",
    "isOldToken",
    "mediaProgress",
    "seriesHideFromContinueListening",
    "bookmarks",
    "isActive",
    "isLocked",
    "createdAt",
    "permissions",
    "librariesAccessible",
    "itemTagsSelected",
    "hasOpenIDLink"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The patron's portal identity id, as a string.",
      "example": "li_8f14e45fceea467f"
    },
    "username": {
      "type": "string",
      "description": "The name the patron signs in with.",
      "example": "riley"
    },
    "email": {
      "type": [
        "string",
        "null"
      ],
      "description": "The patron's email address, if the library has one.",
      "example": "riley@example.com"
    },
    "type": {
      "type": "string",
      "description": "Always `user`: no app is given administrator powers.",
      "example": "user"
    },
    "token": {
      "type": "string",
      "description": "The access token, for apps that read it from here (older apps\nsend this one as their bearer). Empty where the answer is not a\nsign-in.",
      "example": "eyJhbGciOi..."
    },
    "accessToken": {
      "type": [
        "string",
        "null"
      ],
      "description": "The card's access token, on sign-in and refresh answers only.",
      "example": "eyJhbGciOi..."
    },
    "refreshToken": {
      "type": [
        "string",
        "null"
      ],
      "description": "The card's refresh token, on sign-in and refresh answers only.",
      "example": "eyJhbGciOi..."
    },
    "isOldToken": {
      "type": "boolean",
      "description": "Always false: tokens are never the old non-expiring kind.",
      "example": false
    },
    "mediaProgress": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "The patron's progress on one item.",
        "required": [
          "id",
          "userId",
          "libraryItemId",
          "mediaItemId",
          "mediaItemType",
          "duration",
          "progress",
          "currentTime",
          "isFinished",
          "hideFromContinueListening",
          "lastUpdate",
          "startedAt"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The progress id: the item id (one record per patron and item).",
            "example": "li_8f14e45fceea467f"
          },
          "userId": {
            "type": "string",
            "description": "The patron's id.",
            "example": "42"
          },
          "libraryItemId": {
            "type": "string",
            "description": "The item id.",
            "example": "li_8f14e45fceea467f"
          },
          "episodeId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "mediaItemId": {
            "type": "string",
            "description": "The media id: the item id.",
            "example": "li_8f14e45fceea467f"
          },
          "mediaItemType": {
            "type": "string",
            "description": "Always `book`.",
            "example": "book"
          },
          "duration": {
            "type": "number",
            "format": "double",
            "description": "The book's length in seconds, as last reported.",
            "example": 36000.0
          },
          "progress": {
            "type": "number",
            "format": "double",
            "description": "The share listened, from 0 to 1.",
            "example": 0.05
          },
          "currentTime": {
            "type": "number",
            "format": "double",
            "description": "Where the patron is, in seconds.",
            "example": 1830.5
          },
          "isFinished": {
            "type": "boolean",
            "description": "Whether the patron finished it.",
            "example": false
          },
          "hideFromContinueListening": {
            "type": "boolean",
            "description": "Whether it is hidden from continue listening.",
            "example": false
          },
          "ebookLocation": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "ebookProgress": {
            "type": [
              "number",
              "null"
            ],
            "format": "double",
            "description": "Always null.",
            "example": null
          },
          "lastUpdate": {
            "type": "integer",
            "format": "int64",
            "description": "When the progress last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "startedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the patron started, in epoch milliseconds.",
            "example": 1763620000000
          },
          "finishedAt": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "When the patron finished, in epoch milliseconds.",
            "example": null
          }
        }
      },
      "description": "Progress on every item the patron has started."
    },
    "seriesHideFromContinueListening": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Series hidden from continue listening: none.",
      "example": []
    },
    "bookmarks": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A bookmark.",
        "required": [
          "libraryItemId",
          "title",
          "time",
          "createdAt"
        ],
        "properties": {
          "libraryItemId": {
            "type": "string",
            "description": "The item it is in.",
            "example": "li_8f14e45fceea467f"
          },
          "title": {
            "type": "string",
            "description": "Its title.",
            "example": "The First"
          },
          "time": {
            "type": "number",
            "format": "double",
            "description": "Where it is, in seconds.",
            "example": 1830.0
          },
          "createdAt": {
            "type": "integer",
            "format": "int64",
            "description": "When it was made, in epoch milliseconds.",
            "example": 1763600000000
          }
        }
      },
      "description": "Every bookmark the patron has made."
    },
    "isActive": {
      "type": "boolean",
      "description": "Always true: a disabled patron cannot sign in.",
      "example": true
    },
    "isLocked": {
      "type": "boolean",
      "description": "Always false.",
      "example": false
    },
    "lastSeen": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "When the patron was last seen, in epoch milliseconds.",
      "example": 1763630000000
    },
    "createdAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the patron joined, in epoch milliseconds.",
      "example": 1763600000000
    },
    "permissions": {
      "type": "object",
      "description": "What the patron may do.",
      "required": [
        "download",
        "update",
        "delete",
        "upload",
        "createEreader",
        "accessAllLibraries",
        "accessAllTags",
        "accessExplicitContent",
        "selectedTagsNotAccessible"
      ],
      "properties": {
        "download": {
          "type": "boolean",
          "description": "Whether the patron may download items to the device.",
          "example": true
        },
        "update": {
          "type": "boolean",
          "description": "Always false: apps edit nothing.",
          "example": false
        },
        "delete": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "upload": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "createEreader": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "accessAllLibraries": {
          "type": "boolean",
          "description": "Always true: the libraries listed are the ones the patron sees.",
          "example": true
        },
        "accessAllTags": {
          "type": "boolean",
          "description": "Always true.",
          "example": true
        },
        "accessExplicitContent": {
          "type": "boolean",
          "description": "Always true: scope, not an explicit flag, decides visibility.",
          "example": true
        },
        "selectedTagsNotAccessible": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        }
      }
    },
    "librariesAccessible": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Libraries the patron may open, by id.",
      "example": [
        "bookclerk-library"
      ]
    },
    "itemTagsSelected": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags that limit what the patron sees: none (scope is applied by\nthe host, not by tags).",
      "example": []
    },
    "hasOpenIDLink": {
      "type": "boolean",
      "description": "Whether the patron signed in through the browser at least once.",
      "example": false
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries

Lists the libraries the patron may open: the one library.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Responses

  • 200The library. Body: Libraries (application/json)1 field
    • librariesarray of LibraryrequiredThe libraries the patron may open.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The library.

{
  "libraries": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author",
      "folders": [],
      "displayOrder": 1,
      "icon": "audiobookshelf",
      "mediaType": "book",
      "provider": "audible",
      "settings": {
        "coverAspectRatio": 1,
        "disableWatcher": false,
        "audiobooksOnly": true,
        "hideSingleBookSeries": false,
        "onlyShowLaterBooksInContinueSeries": false,
        "epubsAllowScriptedContent": false,
        "markAsFinishedPercentComplete": null,
        "markAsFinishedTimeRemaining": 10
      },
      "lastScan": null,
      "lastScanVersion": "2.17.0",
      "createdAt": 1763600000000,
      "lastUpdate": 1763630000000
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/libraries`.",
  "required": [
    "libraries"
  ],
  "properties": {
    "libraries": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One library an app can open.",
        "required": [
          "id",
          "name",
          "folders",
          "displayOrder",
          "icon",
          "mediaType",
          "provider",
          "settings",
          "createdAt",
          "lastUpdate"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "The library's name.",
            "example": "Ann Author"
          },
          "folders": {
            "type": "array",
            "items": {
              "type": "object"
            },
            "description": "Folders on disk: none are shown.",
            "example": []
          },
          "displayOrder": {
            "type": "integer",
            "format": "int32",
            "description": "The library's place in the list, from 1.",
            "example": 1,
            "minimum": 0
          },
          "icon": {
            "type": "string",
            "description": "The icon apps show (`audiobookshelf` names a book stack).",
            "example": "audiobookshelf"
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "provider": {
            "type": "string",
            "description": "The metadata provider apps show: none.",
            "example": "audible"
          },
          "settings": {
            "type": "object",
            "description": "Display settings.",
            "required": [
              "coverAspectRatio",
              "disableWatcher",
              "audiobooksOnly",
              "hideSingleBookSeries",
              "onlyShowLaterBooksInContinueSeries",
              "epubsAllowScriptedContent",
              "markAsFinishedTimeRemaining"
            ],
            "properties": {
              "coverAspectRatio": {
                "type": "integer",
                "format": "int32",
                "description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
                "example": 1,
                "minimum": 0
              },
              "disableWatcher": {
                "type": "boolean",
                "description": "Always true: the library is not a watched folder.",
                "example": false
              },
              "audiobooksOnly": {
                "type": "boolean",
                "description": "Always true: audiobooks only.",
                "example": true
              },
              "hideSingleBookSeries": {
                "type": "boolean",
                "description": "Whether one-book series are hidden from the series list: no.",
                "example": false
              },
              "onlyShowLaterBooksInContinueSeries": {
                "type": "boolean",
                "description": "Whether continue series skips earlier books: no.",
                "example": false
              },
              "epubsAllowScriptedContent": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "markAsFinishedPercentComplete": {
                "type": [
                  "number",
                  "null"
                ],
                "format": "double",
                "description": "An item counts as finished at this share listened, in percent.",
                "example": null
              },
              "markAsFinishedTimeRemaining": {
                "type": "number",
                "format": "double",
                "description": "An item counts as finished with this many seconds left.",
                "example": 10
              }
            }
          },
          "lastScan": {
            "type": [
              "integer",
              "null"
            ],
            "format": "int64",
            "description": "Always null.",
            "example": null
          },
          "lastScanVersion": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": "2.17.0"
          },
          "createdAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the library was made, in epoch milliseconds.",
            "example": 1763600000000
          },
          "lastUpdate": {
            "type": "integer",
            "format": "int64",
            "description": "When it last changed, in epoch milliseconds.",
            "example": 1763630000000
          }
        }
      },
      "description": "The libraries the patron may open."
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}

Reads the library.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.
  • includequerystringfilterdata to add the filter values.

Responses

  • 200The library. Body: LibraryAnswer (application/json)
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The library.

{
  "filterdata": {
    "authors": [
      {
        "id": "li_8f14e45fceea467f",
        "name": "Ann Author"
      }
    ],
    "genres": [
      "Fantasy"
    ],
    "tags": [],
    "series": [
      {
        "id": "li_8f14e45fceea467f",
        "name": "Ann Author"
      }
    ],
    "narrators": [
      "Nia Narrator"
    ],
    "languages": [
      "en-us"
    ],
    "publishers": [
      "Example Press"
    ],
    "publishedDecades": [
      "2020"
    ],
    "bookCount": 1,
    "authorCount": 1,
    "seriesCount": 1,
    "podcastCount": 0,
    "numberEpisodes": 0,
    "loadedAt": 1763630000000
  },
  "issues": 0,
  "numUserPlaylists": 0,
  "library": {
    "id": "li_8f14e45fceea467f",
    "name": "Ann Author",
    "folders": [],
    "displayOrder": 1,
    "icon": "audiobookshelf",
    "mediaType": "book",
    "provider": "audible",
    "settings": {
      "coverAspectRatio": 1,
      "disableWatcher": false,
      "audiobooksOnly": true,
      "hideSingleBookSeries": false,
      "onlyShowLaterBooksInContinueSeries": false,
      "epubsAllowScriptedContent": false,
      "markAsFinishedPercentComplete": null,
      "markAsFinishedTimeRemaining": 10
    },
    "lastScan": null,
    "lastScanVersion": "2.17.0",
    "createdAt": 1763600000000,
    "lastUpdate": 1763630000000
  }
}

Schema:

{
  "oneOf": [
    {
      "type": "object",
      "description": "With `include=filterdata`.",
      "required": [
        "filterdata",
        "issues",
        "numUserPlaylists",
        "library"
      ],
      "properties": {
        "filterdata": {
          "type": "object",
          "description": "The filter values.",
          "required": [
            "authors",
            "genres",
            "tags",
            "series",
            "narrators",
            "languages",
            "publishers",
            "publishedDecades",
            "bookCount",
            "authorCount",
            "seriesCount",
            "podcastCount",
            "numberEpisodes",
            "loadedAt"
          ],
          "properties": {
            "authors": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "An id and a name.",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The entity's id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "name": {
                    "type": "string",
                    "description": "Its display name.",
                    "example": "Ann Author"
                  }
                }
              },
              "description": "Authors with at least one item."
            },
            "genres": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Genres.",
              "example": [
                "Fantasy"
              ]
            },
            "tags": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Tags: none are shown.",
              "example": []
            },
            "series": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "An id and a name.",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The entity's id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "name": {
                    "type": "string",
                    "description": "Its display name.",
                    "example": "Ann Author"
                  }
                }
              },
              "description": "Series with at least one item."
            },
            "narrators": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Narrators.",
              "example": [
                "Nia Narrator"
              ]
            },
            "languages": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Languages.",
              "example": [
                "en-us"
              ]
            },
            "publishers": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Publishers.",
              "example": [
                "Example Press"
              ]
            },
            "publishedDecades": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Decades of publication: none are offered.",
              "example": [
                "2020"
              ]
            },
            "bookCount": {
              "type": "integer",
              "format": "int64",
              "description": "Items in the library.",
              "example": 1,
              "minimum": 0
            },
            "authorCount": {
              "type": "integer",
              "format": "int64",
              "description": "Authors in the library.",
              "example": 1,
              "minimum": 0
            },
            "seriesCount": {
              "type": "integer",
              "format": "int64",
              "description": "Series in the library.",
              "example": 1,
              "minimum": 0
            },
            "podcastCount": {
              "type": "integer",
              "format": "int64",
              "description": "Always 0.",
              "example": 0,
              "minimum": 0
            },
            "numberEpisodes": {
              "type": "integer",
              "format": "int64",
              "description": "Always 0.",
              "example": 0,
              "minimum": 0
            },
            "loadedAt": {
              "type": "integer",
              "format": "int64",
              "description": "When the values were read, in epoch milliseconds.",
              "example": 1763630000000
            }
          }
        },
        "issues": {
          "type": "integer",
          "format": "int64",
          "description": "Items with problems: none are reported.",
          "example": 0,
          "minimum": 0
        },
        "numUserPlaylists": {
          "type": "integer",
          "format": "int64",
          "description": "The patron's playlists in the library: none.",
          "example": 0,
          "minimum": 0
        },
        "library": {
          "type": "object",
          "description": "The library.",
          "required": [
            "id",
            "name",
            "folders",
            "displayOrder",
            "icon",
            "mediaType",
            "provider",
            "settings",
            "createdAt",
            "lastUpdate"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
              "example": "li_8f14e45fceea467f"
            },
            "name": {
              "type": "string",
              "description": "The library's name.",
              "example": "Ann Author"
            },
            "folders": {
              "type": "array",
              "items": {
                "type": "object"
              },
              "description": "Folders on disk: none are shown.",
              "example": []
            },
            "displayOrder": {
              "type": "integer",
              "format": "int32",
              "description": "The library's place in the list, from 1.",
              "example": 1,
              "minimum": 0
            },
            "icon": {
              "type": "string",
              "description": "The icon apps show (`audiobookshelf` names a book stack).",
              "example": "audiobookshelf"
            },
            "mediaType": {
              "type": "string",
              "description": "Always [`MEDIA_TYPE_BOOK`].",
              "example": "book"
            },
            "provider": {
              "type": "string",
              "description": "The metadata provider apps show: none.",
              "example": "audible"
            },
            "settings": {
              "type": "object",
              "description": "Display settings.",
              "required": [
                "coverAspectRatio",
                "disableWatcher",
                "audiobooksOnly",
                "hideSingleBookSeries",
                "onlyShowLaterBooksInContinueSeries",
                "epubsAllowScriptedContent",
                "markAsFinishedTimeRemaining"
              ],
              "properties": {
                "coverAspectRatio": {
                  "type": "integer",
                  "format": "int32",
                  "description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
                  "example": 1,
                  "minimum": 0
                },
                "disableWatcher": {
                  "type": "boolean",
                  "description": "Always true: the library is not a watched folder.",
                  "example": false
                },
                "audiobooksOnly": {
                  "type": "boolean",
                  "description": "Always true: audiobooks only.",
                  "example": true
                },
                "hideSingleBookSeries": {
                  "type": "boolean",
                  "description": "Whether one-book series are hidden from the series list: no.",
                  "example": false
                },
                "onlyShowLaterBooksInContinueSeries": {
                  "type": "boolean",
                  "description": "Whether continue series skips earlier books: no.",
                  "example": false
                },
                "epubsAllowScriptedContent": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "markAsFinishedPercentComplete": {
                  "type": [
                    "number",
                    "null"
                  ],
                  "format": "double",
                  "description": "An item counts as finished at this share listened, in percent.",
                  "example": null
                },
                "markAsFinishedTimeRemaining": {
                  "type": "number",
                  "format": "double",
                  "description": "An item counts as finished with this many seconds left.",
                  "example": 10
                }
              }
            },
            "lastScan": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "Always null.",
              "example": null
            },
            "lastScanVersion": {
              "type": [
                "string",
                "null"
              ],
              "description": "Always null.",
              "example": "2.17.0"
            },
            "createdAt": {
              "type": "integer",
              "format": "int64",
              "description": "When the library was made, in epoch milliseconds.",
              "example": 1763600000000
            },
            "lastUpdate": {
              "type": "integer",
              "format": "int64",
              "description": "When it last changed, in epoch milliseconds.",
              "example": 1763630000000
            }
          }
        }
      }
    },
    {
      "type": "object",
      "description": "Otherwise.",
      "required": [
        "id",
        "name",
        "folders",
        "displayOrder",
        "icon",
        "mediaType",
        "provider",
        "settings",
        "createdAt",
        "lastUpdate"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The library id ([`crate::ids::WHOLE_LIBRARY_ID`] for the whole\nlibrary).",
          "example": "li_8f14e45fceea467f"
        },
        "name": {
          "type": "string",
          "description": "The library's name.",
          "example": "Ann Author"
        },
        "folders": {
          "type": "array",
          "items": {
            "type": "object"
          },
          "description": "Folders on disk: none are shown.",
          "example": []
        },
        "displayOrder": {
          "type": "integer",
          "format": "int32",
          "description": "The library's place in the list, from 1.",
          "example": 1,
          "minimum": 0
        },
        "icon": {
          "type": "string",
          "description": "The icon apps show (`audiobookshelf` names a book stack).",
          "example": "audiobookshelf"
        },
        "mediaType": {
          "type": "string",
          "description": "Always [`MEDIA_TYPE_BOOK`].",
          "example": "book"
        },
        "provider": {
          "type": "string",
          "description": "The metadata provider apps show: none.",
          "example": "audible"
        },
        "settings": {
          "type": "object",
          "description": "Display settings.",
          "required": [
            "coverAspectRatio",
            "disableWatcher",
            "audiobooksOnly",
            "hideSingleBookSeries",
            "onlyShowLaterBooksInContinueSeries",
            "epubsAllowScriptedContent",
            "markAsFinishedTimeRemaining"
          ],
          "properties": {
            "coverAspectRatio": {
              "type": "integer",
              "format": "int32",
              "description": "1 for square covers, 2 for the 1.6:1 book shape: square.",
              "example": 1,
              "minimum": 0
            },
            "disableWatcher": {
              "type": "boolean",
              "description": "Always true: the library is not a watched folder.",
              "example": false
            },
            "audiobooksOnly": {
              "type": "boolean",
              "description": "Always true: audiobooks only.",
              "example": true
            },
            "hideSingleBookSeries": {
              "type": "boolean",
              "description": "Whether one-book series are hidden from the series list: no.",
              "example": false
            },
            "onlyShowLaterBooksInContinueSeries": {
              "type": "boolean",
              "description": "Whether continue series skips earlier books: no.",
              "example": false
            },
            "epubsAllowScriptedContent": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "markAsFinishedPercentComplete": {
              "type": [
                "number",
                "null"
              ],
              "format": "double",
              "description": "An item counts as finished at this share listened, in percent.",
              "example": null
            },
            "markAsFinishedTimeRemaining": {
              "type": "number",
              "format": "double",
              "description": "An item counts as finished with this many seconds left.",
              "example": 10
            }
          }
        },
        "lastScan": {
          "type": [
            "integer",
            "null"
          ],
          "format": "int64",
          "description": "Always null.",
          "example": null
        },
        "lastScanVersion": {
          "type": [
            "string",
            "null"
          ],
          "description": "Always null.",
          "example": "2.17.0"
        },
        "createdAt": {
          "type": "integer",
          "format": "int64",
          "description": "When the library was made, in epoch milliseconds.",
          "example": 1763600000000
        },
        "lastUpdate": {
          "type": "integer",
          "format": "int64",
          "description": "When it last changed, in epoch milliseconds.",
          "example": 1763630000000
        }
      }
    }
  ],
  "description": "`GET /player/api/libraries/{id}` answer: the library, with its filter\nvalues when asked for (`include=filterdata`)."
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/items

Lists the library's items, one page at a time.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.
  • limitqueryinteger (int64)Items per page, at most 1000; 0 for all (up to 1000).
  • pagequeryinteger (int64)Page number, from 0.
  • sortquerystringmedia.metadata.title, media.metadata.authorName, addedAt, media.duration or sequence.
  • descqueryinteger (int32)1 to reverse the order.
  • filterquerystringgroup.base64value: authors, series, genres, tags, narrators, publishers or progress.
  • includequerystringprogress to add the patron's progress.
  • minifiedqueryinteger (int32)Accepted; items are always the short shape.

Responses

  • 200A page of items. Body: ItemPage (application/json)12 fields
    • resultsarray of LibraryItemrequiredThe page's items.
    • totalinteger (int64)requiredItems matching the query in all. At least 0.
    • limitinteger (int64)requiredItems per page (0: no paging). At least 0.
    • pageinteger (int64)requiredThe page number, from 0. At least 0.
    • sortBystring or nullThe sort key the app sent, echoed.
    • sortDescbooleanrequiredWhether the order is reversed.
    • filterBystring or nullThe filter the app sent, echoed.
    • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
    • minifiedbooleanrequiredWhether items are minified.
    • collapseseriesbooleanrequiredWhether series were collapsed: never.
    • includestringrequiredThe include list the app sent, echoed.
    • offsetinteger (int64)requiredThe offset of the first result. At least 0.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/items' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/items' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/items",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/items", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/items")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: A page of items.

{
  "results": [
    {
      "id": "li_8f14e45fceea467f",
      "ino": "0",
      "oldLibraryItemId": null,
      "libraryId": "bookclerk-library",
      "folderId": "bookclerk-library",
      "path": "/the-first.m4b",
      "relPath": "the-first.m4b",
      "isFile": true,
      "mtimeMs": 1763600000000,
      "ctimeMs": 1763600000000,
      "birthtimeMs": 1763600000000,
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "id": "li_8f14e45fceea467f",
        "libraryItemId": "li_8f14e45fceea467f",
        "metadata": {
          "title": "The First",
          "titleIgnorePrefix": "First, The",
          "authors": [],
          "authorName": "Ann Author",
          "authorNameLF": "Author, Ann",
          "narrators": [
            "Nia Narrator"
          ],
          "narratorName": "Nia Narrator",
          "series": [],
          "seriesName": "The Saga #1",
          "genres": [
            "Fantasy"
          ],
          "explicit": false,
          "abridged": false
        },
        "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
        "tags": [],
        "numTracks": 1,
        "numAudioFiles": 1,
        "numChapters": 0,
        "duration": 36000.0,
        "size": 100000,
        "audioFiles": [],
        "chapters": [],
        "tracks": []
      },
      "numFiles": 1,
      "size": 100000,
      "libraryFiles": [
        {
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "fileType": "audio"
        }
      ],
      "userMediaProgress": {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      },
      "seriesSequence": "1"
    }
  ],
  "total": 1,
  "limit": 20,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": null,
  "mediaType": "book",
  "minified": false,
  "collapseseries": false,
  "include": "",
  "offset": 0
}

Schema:

{
  "type": "object",
  "description": "A page of items: `GET /api/libraries/{id}/items` and the like.",
  "required": [
    "results",
    "total",
    "limit",
    "page",
    "sortDesc",
    "mediaType",
    "minified",
    "collapseseries",
    "include",
    "offset"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An item: an edition with a stored copy.",
        "required": [
          "id",
          "ino",
          "libraryId",
          "folderId",
          "path",
          "relPath",
          "isFile",
          "mtimeMs",
          "ctimeMs",
          "birthtimeMs",
          "addedAt",
          "updatedAt",
          "isMissing",
          "isInvalid",
          "mediaType",
          "media",
          "numFiles",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id: the edition id.",
            "example": "li_8f14e45fceea467f"
          },
          "ino": {
            "type": "string",
            "description": "The item's inode as apps expect one: the edition id again.",
            "example": "0"
          },
          "oldLibraryItemId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library the item is listed in.",
            "example": "bookclerk-library"
          },
          "folderId": {
            "type": "string",
            "description": "The folder id: the library id.",
            "example": "bookclerk-library"
          },
          "path": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "/the-first.m4b"
          },
          "relPath": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "the-first.m4b"
          },
          "isFile": {
            "type": "boolean",
            "description": "Always false: an item is a folder of tracks.",
            "example": true
          },
          "mtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy last changed, in epoch milliseconds.",
            "example": 1763600000000
          },
          "ctimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "birthtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the item joined the library, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When its record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "isMissing": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "isInvalid": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "media": {
            "type": "object",
            "description": "The book.",
            "required": [
              "id",
              "metadata",
              "tags",
              "numTracks",
              "numAudioFiles",
              "numChapters",
              "duration",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The media id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "libraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item id, when fetched expanded.",
                "example": "li_8f14e45fceea467f"
              },
              "metadata": {
                "type": "object",
                "description": "The book's metadata.",
                "required": [
                  "title",
                  "titleIgnorePrefix",
                  "authors",
                  "authorName",
                  "authorNameLF",
                  "narrators",
                  "narratorName",
                  "series",
                  "seriesName",
                  "genres",
                  "explicit",
                  "abridged"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title.",
                    "example": "The First"
                  },
                  "titleIgnorePrefix": {
                    "type": "string",
                    "description": "The title for sorting.",
                    "example": "First, The"
                  },
                  "subtitle": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The subtitle, if any.",
                    "example": "A Novel"
                  },
                  "authors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "An id and a name.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The entity's id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "Its display name.",
                          "example": "Ann Author"
                        }
                      }
                    },
                    "description": "The authors."
                  },
                  "authorName": {
                    "type": "string",
                    "description": "The authors' names joined with `, `.",
                    "example": "Ann Author"
                  },
                  "authorNameLF": {
                    "type": "string",
                    "description": "The authors' names, family name first, joined with `, `.",
                    "example": "Author, Ann"
                  },
                  "narrators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The narrators' names.",
                    "example": [
                      "Nia Narrator"
                    ]
                  },
                  "narratorName": {
                    "type": "string",
                    "description": "The narrators' names joined with `, `.",
                    "example": "Nia Narrator"
                  },
                  "series": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A series an item belongs to, with the item's place in it.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The series id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "The series name.",
                          "example": "Ann Author"
                        },
                        "sequence": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                          "example": "1"
                        }
                      }
                    },
                    "description": "The series the book is in."
                  },
                  "seriesName": {
                    "type": "string",
                    "description": "The series names with the book's place (`Name #2`), joined.",
                    "example": "The Saga #1"
                  },
                  "genres": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Genres.",
                    "example": [
                      "Fantasy"
                    ]
                  },
                  "publishedYear": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The year of publication, as a string (`\"2019\"`).",
                    "example": "2024"
                  },
                  "publishedDate": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The date of publication, if known.",
                    "example": "2024-03-01"
                  },
                  "publisher": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The publisher.",
                    "example": "Example Press"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description, as the library stores it.",
                    "example": "A short description."
                  },
                  "descriptionPlain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description with markup removed.",
                    "example": "A short description."
                  },
                  "isbn": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ISBN, if known.",
                    "example": "9780000000002"
                  },
                  "asin": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ASIN, if known.",
                    "example": "B000000000"
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The language.",
                    "example": "en-us"
                  },
                  "explicit": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "abridged": {
                    "type": "boolean",
                    "description": "Whether the edition is abridged.",
                    "example": false
                  }
                }
              },
              "coverPath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                "example": "/player/api/items/li_8f14e45fceea467f/cover"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tags: none.",
                "example": []
              },
              "numTracks": {
                "type": "integer",
                "format": "int64",
                "description": "Tracks in play order.",
                "example": 1,
                "minimum": 0
              },
              "numAudioFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Audio files.",
                "example": 1,
                "minimum": 0
              },
              "numChapters": {
                "type": "integer",
                "format": "int64",
                "description": "Chapters.",
                "example": 0,
                "minimum": 0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds.",
                "example": 36000.0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in its audio files.",
                "example": 100000,
                "minimum": 0
              },
              "audioFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An audio file of a book.",
                  "required": [
                    "index",
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "manuallyVerified",
                    "exclude",
                    "duration",
                    "chapters",
                    "metaTags",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "trackNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number the file's tags state: not read.",
                      "example": 1,
                      "minimum": 0
                    },
                    "discNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number the file's tags state: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "trackNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "discNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "manuallyVerified": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "exclude": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "format": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The container format, such as `mp4` or `mp3`.",
                      "example": "MP4A"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The file's length in seconds.",
                      "example": 36000.0
                    },
                    "bitRate": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Bits per second, if known.",
                      "example": 128000,
                      "minimum": 0
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The file's language, if known.",
                      "example": "en-us"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "timeBase": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The time base, if known.",
                      "example": "1/44100"
                    },
                    "channels": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Audio channels, if known.",
                      "example": 2,
                      "minimum": 0
                    },
                    "channelLayout": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel layout, if known.",
                      "example": "stereo"
                    },
                    "chapters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "Chapters embedded in the file: none are read."
                    },
                    "embeddedCoverArt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "metaTags": {
                      "type": "object",
                      "description": "Tags read from the file: none until the stored media probe reads\nthem."
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The file's media type, such as `audio/mp4`.",
                      "example": "audio/mp4"
                    }
                  }
                },
                "description": "The audio files, when fetched expanded."
              },
              "chapters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "The chapters, when fetched expanded."
              },
              "tracks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A track with its place in the book.",
                  "required": [
                    "index",
                    "startOffset",
                    "duration",
                    "title",
                    "contentUrl",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The track's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "startOffset": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the track starts in the book, in seconds.",
                      "example": 0.0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The track's length in seconds.",
                      "example": 36000.0
                    },
                    "title": {
                      "type": "string",
                      "description": "The track's title: its file name.",
                      "example": "The First"
                    },
                    "contentUrl": {
                      "type": "string",
                      "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The track's media type.",
                      "example": "audio/mp4"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "metadata": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                },
                "description": "The tracks with their place in the book, when fetched expanded."
              }
            }
          },
          "numFiles": {
            "type": "integer",
            "format": "int64",
            "description": "Files in the item.",
            "example": 1,
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes in all its files.",
            "example": 100000,
            "minimum": 0
          },
          "libraryFiles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A file of an item, in the expanded item's `libraryFiles`.",
              "required": [
                "ino",
                "metadata",
                "addedAt",
                "updatedAt",
                "fileType"
              ],
              "properties": {
                "ino": {
                  "type": "string",
                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                  "example": "0"
                },
                "metadata": {
                  "type": "object",
                  "description": "The file's name, size and times.",
                  "required": [
                    "filename",
                    "ext",
                    "path",
                    "relPath",
                    "size",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs"
                  ],
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The file name.",
                      "example": "the-first.m4b"
                    },
                    "ext": {
                      "type": "string",
                      "description": "The extension with its dot (`.m4b`).",
                      "example": ".m4b"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "the-first.m4b"
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's size in bytes.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    }
                  }
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "fileType": {
                  "type": "string",
                  "description": "Always `audio`.",
                  "example": "audio"
                }
              }
            },
            "description": "The item's files, when the item is fetched expanded."
          },
          "userMediaProgress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress, when the app asked for it.",
                "required": [
                  "id",
                  "userId",
                  "libraryItemId",
                  "mediaItemId",
                  "mediaItemType",
                  "duration",
                  "progress",
                  "currentTime",
                  "isFinished",
                  "hideFromContinueListening",
                  "lastUpdate",
                  "startedAt"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The progress id: the item id (one record per patron and item).",
                    "example": "li_8f14e45fceea467f"
                  },
                  "userId": {
                    "type": "string",
                    "description": "The patron's id.",
                    "example": "42"
                  },
                  "libraryItemId": {
                    "type": "string",
                    "description": "The item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "episodeId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "mediaItemId": {
                    "type": "string",
                    "description": "The media id: the item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "mediaItemType": {
                    "type": "string",
                    "description": "Always `book`.",
                    "example": "book"
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds, as last reported.",
                    "example": 36000.0
                  },
                  "progress": {
                    "type": "number",
                    "format": "double",
                    "description": "The share listened, from 0 to 1.",
                    "example": 0.05
                  },
                  "currentTime": {
                    "type": "number",
                    "format": "double",
                    "description": "Where the patron is, in seconds.",
                    "example": 1830.5
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished it.",
                    "example": false
                  },
                  "hideFromContinueListening": {
                    "type": "boolean",
                    "description": "Whether it is hidden from continue listening.",
                    "example": false
                  },
                  "ebookLocation": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "ebookProgress": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "format": "double",
                    "description": "Always null.",
                    "example": null
                  },
                  "lastUpdate": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the progress last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "startedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the patron started, in epoch milliseconds.",
                    "example": 1763620000000
                  },
                  "finishedAt": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "When the patron finished, in epoch milliseconds.",
                    "example": null
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "seriesSequence": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's place in a series, on a series' book list.",
            "example": "1"
          }
        }
      },
      "description": "The page's items."
    },
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "Items matching the query in all.",
      "example": 1,
      "minimum": 0
    },
    "limit": {
      "type": "integer",
      "format": "int64",
      "description": "Items per page (0: no paging).",
      "example": 20,
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "format": "int64",
      "description": "The page number, from 0.",
      "example": 0,
      "minimum": 0
    },
    "sortBy": {
      "type": [
        "string",
        "null"
      ],
      "description": "The sort key the app sent, echoed.",
      "example": "media.metadata.title"
    },
    "sortDesc": {
      "type": "boolean",
      "description": "Whether the order is reversed.",
      "example": false
    },
    "filterBy": {
      "type": [
        "string",
        "null"
      ],
      "description": "The filter the app sent, echoed.",
      "example": null
    },
    "mediaType": {
      "type": "string",
      "description": "Always [`MEDIA_TYPE_BOOK`].",
      "example": "book"
    },
    "minified": {
      "type": "boolean",
      "description": "Whether items are minified.",
      "example": false
    },
    "collapseseries": {
      "type": "boolean",
      "description": "Whether series were collapsed: never.",
      "example": false
    },
    "include": {
      "type": "string",
      "description": "The include list the app sent, echoed.",
      "example": ""
    },
    "offset": {
      "type": "integer",
      "format": "int64",
      "description": "The offset of the first result.",
      "example": 0,
      "minimum": 0
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/series

Lists the library's series, one page at a time.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.
  • limitqueryinteger (int64)Series per page; 0 for all (up to 1000).
  • pagequeryinteger (int64)Page number, from 0.
  • descqueryinteger (int32)1 for Z to A.

Responses

  • 200A page of series, each with its items. Body: SeriesPage (application/json)9 fields
    • resultsarray of SeriesrequiredThe page's series.
    • totalinteger (int64)requiredSeries in all. At least 0.
    • limitinteger (int64)requiredSeries per page. At least 0.
    • pageinteger (int64)requiredThe page number, from 0. At least 0.
    • sortBystring or nullThe sort key, echoed.
    • sortDescbooleanrequiredWhether the order is reversed.
    • filterBystring or nullThe filter, echoed.
    • minifiedbooleanrequiredWhether items are minified.
    • includestringrequiredThe include list, echoed.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/series' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/series' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/series",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/series", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/series")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: A page of series, each with its items.

{
  "results": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author",
      "nameIgnorePrefix": "Saga, The",
      "description": "A short description.",
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "libraryId": "bookclerk-library",
      "books": [
        {
          "id": "li_8f14e45fceea467f",
          "ino": "0",
          "libraryId": "bookclerk-library",
          "folderId": "bookclerk-library",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "isFile": true,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000,
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "id": "li_8f14e45fceea467f",
            "metadata": {
              "title": "The First",
              "titleIgnorePrefix": "First, The",
              "authors": [],
              "authorName": "Ann Author",
              "authorNameLF": "Author, Ann",
              "narrators": [
                "Nia Narrator"
              ],
              "narratorName": "Nia Narrator",
              "series": [],
              "seriesName": "The Saga #1",
              "genres": [
                "Fantasy"
              ],
              "explicit": false,
              "abridged": false
            },
            "tags": [],
            "numTracks": 1,
            "numAudioFiles": 1,
            "numChapters": 0,
            "duration": 36000.0,
            "size": 100000
          },
          "numFiles": 1,
          "size": 100000
        }
      ],
      "progress": {
        "libraryItemIds": [
          "li_8f14e45fceea467f"
        ],
        "libraryItemIdsFinished": [],
        "isFinished": false
      }
    }
  ],
  "total": 1,
  "limit": 20,
  "page": 0,
  "sortBy": "media.metadata.title",
  "sortDesc": false,
  "filterBy": null,
  "minified": false,
  "include": ""
}

Schema:

{
  "type": "object",
  "description": "A page of series.",
  "required": [
    "results",
    "total",
    "limit",
    "page",
    "sortDesc",
    "minified",
    "include"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A series.",
        "required": [
          "id",
          "name",
          "nameIgnorePrefix",
          "addedAt",
          "updatedAt",
          "libraryId"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The series id.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "Its name.",
            "example": "Ann Author"
          },
          "nameIgnorePrefix": {
            "type": "string",
            "description": "The name for sorting.",
            "example": "Saga, The"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Its description: none.",
            "example": "A short description."
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the library first saw it, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When it last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "libraryId": {
            "type": "string",
            "description": "The library it is listed in.",
            "example": "bookclerk-library"
          },
          "books": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "Its items in series order, on lists."
          },
          "progress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress through it, when asked for.",
                "required": [
                  "libraryItemIds",
                  "libraryItemIdsFinished",
                  "isFinished"
                ],
                "properties": {
                  "libraryItemIds": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The series' items, by id.",
                    "example": [
                      "li_8f14e45fceea467f"
                    ]
                  },
                  "libraryItemIdsFinished": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Those the patron finished.",
                    "example": []
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished every one.",
                    "example": false
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "description": "The page's series."
    },
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "Series in all.",
      "example": 1,
      "minimum": 0
    },
    "limit": {
      "type": "integer",
      "format": "int64",
      "description": "Series per page.",
      "example": 20,
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "format": "int64",
      "description": "The page number, from 0.",
      "example": 0,
      "minimum": 0
    },
    "sortBy": {
      "type": [
        "string",
        "null"
      ],
      "description": "The sort key, echoed.",
      "example": "media.metadata.title"
    },
    "sortDesc": {
      "type": "boolean",
      "description": "Whether the order is reversed.",
      "example": false
    },
    "filterBy": {
      "type": [
        "string",
        "null"
      ],
      "description": "The filter, echoed.",
      "example": null
    },
    "minified": {
      "type": "boolean",
      "description": "Whether items are minified.",
      "example": false
    },
    "include": {
      "type": "string",
      "description": "The include list, echoed.",
      "example": ""
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/authors

Lists the library's authors.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200Every author, by name (up to 5000). Body: Authors (application/json)1 field
    • authorsarray of AuthorrequiredThe authors.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/authors' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/authors' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/authors",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/authors", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/authors")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Every author, by name (up to 5000).

{
  "authors": [
    {
      "id": "li_8f14e45fceea467f",
      "asin": "B000000000",
      "name": "Ann Author",
      "lastFirst": "Author, Ann",
      "description": "A short description.",
      "imagePath": null,
      "libraryId": "bookclerk-library",
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "numBooks": 1,
      "libraryItems": [
        {
          "id": "li_8f14e45fceea467f",
          "ino": "0",
          "libraryId": "bookclerk-library",
          "folderId": "bookclerk-library",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "isFile": true,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000,
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "id": "li_8f14e45fceea467f",
            "metadata": {
              "title": "The First",
              "titleIgnorePrefix": "First, The",
              "authors": [],
              "authorName": "Ann Author",
              "authorNameLF": "Author, Ann",
              "narrators": [
                "Nia Narrator"
              ],
              "narratorName": "Nia Narrator",
              "series": [],
              "seriesName": "The Saga #1",
              "genres": [
                "Fantasy"
              ],
              "explicit": false,
              "abridged": false
            },
            "tags": [],
            "numTracks": 1,
            "numAudioFiles": 1,
            "numChapters": 0,
            "duration": 36000.0,
            "size": 100000
          },
          "numFiles": 1,
          "size": 100000
        }
      ],
      "series": [
        {
          "id": "li_8f14e45fceea467f",
          "name": "Ann Author",
          "items": []
        }
      ]
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/libraries/{id}/authors` without paging.",
  "required": [
    "authors"
  ],
  "properties": {
    "authors": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An author.",
        "required": [
          "id",
          "name",
          "lastFirst",
          "libraryId",
          "addedAt",
          "updatedAt",
          "numBooks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The contributor id.",
            "example": "li_8f14e45fceea467f"
          },
          "asin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": "B000000000"
          },
          "name": {
            "type": "string",
            "description": "The author's name.",
            "example": "Ann Author"
          },
          "lastFirst": {
            "type": "string",
            "description": "The name family name first.",
            "example": "Author, Ann"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": "A short description."
          },
          "imagePath": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null: no author images.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library it is listed in.",
            "example": "bookclerk-library"
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the library first saw the author, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "numBooks": {
            "type": "integer",
            "format": "int64",
            "description": "Items by the author the patron can see.",
            "example": 1,
            "minimum": 0
          },
          "libraryItems": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "The author's items, when asked for."
          },
          "series": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A series of an author's, with the author's items in it.",
              "required": [
                "id",
                "name",
                "items"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The series id.",
                  "example": "li_8f14e45fceea467f"
                },
                "name": {
                  "type": "string",
                  "description": "The series name.",
                  "example": "Ann Author"
                },
                "items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "description": "An item: an edition with a stored copy.",
                    "required": [
                      "id",
                      "ino",
                      "libraryId",
                      "folderId",
                      "path",
                      "relPath",
                      "isFile",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs",
                      "addedAt",
                      "updatedAt",
                      "isMissing",
                      "isInvalid",
                      "mediaType",
                      "media",
                      "numFiles",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The item id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "ino": {
                        "type": "string",
                        "description": "The item's inode as apps expect one: the edition id again.",
                        "example": "0"
                      },
                      "oldLibraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "libraryId": {
                        "type": "string",
                        "description": "The library the item is listed in.",
                        "example": "bookclerk-library"
                      },
                      "folderId": {
                        "type": "string",
                        "description": "The folder id: the library id.",
                        "example": "bookclerk-library"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "the-first.m4b"
                      },
                      "isFile": {
                        "type": "boolean",
                        "description": "Always false: an item is a folder of tracks.",
                        "example": true
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy last changed, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the item joined the library, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When its record last changed, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "isMissing": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "isInvalid": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "mediaType": {
                        "type": "string",
                        "description": "Always [`MEDIA_TYPE_BOOK`].",
                        "example": "book"
                      },
                      "media": {
                        "type": "object",
                        "description": "The book.",
                        "required": [
                          "id",
                          "metadata",
                          "tags",
                          "numTracks",
                          "numAudioFiles",
                          "numChapters",
                          "duration",
                          "size"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The media id: the edition id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "libraryItemId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The item id, when fetched expanded.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The book's metadata.",
                            "required": [
                              "title",
                              "titleIgnorePrefix",
                              "authors",
                              "authorName",
                              "authorNameLF",
                              "narrators",
                              "narratorName",
                              "series",
                              "seriesName",
                              "genres",
                              "explicit",
                              "abridged"
                            ],
                            "properties": {
                              "title": {
                                "type": "string",
                                "description": "The title.",
                                "example": "The First"
                              },
                              "titleIgnorePrefix": {
                                "type": "string",
                                "description": "The title for sorting.",
                                "example": "First, The"
                              },
                              "subtitle": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The subtitle, if any.",
                                "example": "A Novel"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "An id and a name.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The entity's id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "Its display name.",
                                      "example": "Ann Author"
                                    }
                                  }
                                },
                                "description": "The authors."
                              },
                              "authorName": {
                                "type": "string",
                                "description": "The authors' names joined with `, `.",
                                "example": "Ann Author"
                              },
                              "authorNameLF": {
                                "type": "string",
                                "description": "The authors' names, family name first, joined with `, `.",
                                "example": "Author, Ann"
                              },
                              "narrators": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The narrators' names.",
                                "example": [
                                  "Nia Narrator"
                                ]
                              },
                              "narratorName": {
                                "type": "string",
                                "description": "The narrators' names joined with `, `.",
                                "example": "Nia Narrator"
                              },
                              "series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "A series an item belongs to, with the item's place in it.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The series id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "The series name.",
                                      "example": "Ann Author"
                                    },
                                    "sequence": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                      "example": "1"
                                    }
                                  }
                                },
                                "description": "The series the book is in."
                              },
                              "seriesName": {
                                "type": "string",
                                "description": "The series names with the book's place (`Name #2`), joined.",
                                "example": "The Saga #1"
                              },
                              "genres": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Genres.",
                                "example": [
                                  "Fantasy"
                                ]
                              },
                              "publishedYear": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The year of publication, as a string (`\"2019\"`).",
                                "example": "2024"
                              },
                              "publishedDate": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The date of publication, if known.",
                                "example": "2024-03-01"
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The publisher.",
                                "example": "Example Press"
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description, as the library stores it.",
                                "example": "A short description."
                              },
                              "descriptionPlain": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description with markup removed.",
                                "example": "A short description."
                              },
                              "isbn": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ISBN, if known.",
                                "example": "9780000000002"
                              },
                              "asin": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ASIN, if known.",
                                "example": "B000000000"
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The language.",
                                "example": "en-us"
                              },
                              "explicit": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "abridged": {
                                "type": "boolean",
                                "description": "Whether the edition is abridged.",
                                "example": false
                              }
                            }
                          },
                          "coverPath": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/cover"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Tags: none.",
                            "example": []
                          },
                          "numTracks": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Tracks in play order.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numAudioFiles": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Audio files.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numChapters": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Chapters.",
                            "example": 0,
                            "minimum": 0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds.",
                            "example": 36000.0
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Bytes in its audio files.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "audioFiles": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "An audio file of a book.",
                              "required": [
                                "index",
                                "ino",
                                "metadata",
                                "addedAt",
                                "updatedAt",
                                "manuallyVerified",
                                "exclude",
                                "duration",
                                "chapters",
                                "metaTags",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "ino": {
                                  "type": "string",
                                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                  "example": "0"
                                },
                                "metadata": {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                "addedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "updatedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763630000000
                                },
                                "trackNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number the file's tags state: not read.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "discNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number the file's tags state: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "trackNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "discNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "manuallyVerified": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "exclude": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "error": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "format": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The container format, such as `mp4` or `mp3`.",
                                  "example": "MP4A"
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The file's length in seconds.",
                                  "example": 36000.0
                                },
                                "bitRate": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Bits per second, if known.",
                                  "example": 128000,
                                  "minimum": 0
                                },
                                "language": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The file's language, if known.",
                                  "example": "en-us"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "timeBase": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The time base, if known.",
                                  "example": "1/44100"
                                },
                                "channels": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Audio channels, if known.",
                                  "example": 2,
                                  "minimum": 0
                                },
                                "channelLayout": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The channel layout, if known.",
                                  "example": "stereo"
                                },
                                "chapters": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "description": "A chapter of a book.",
                                    "required": [
                                      "id",
                                      "start",
                                      "end",
                                      "title"
                                    ],
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The chapter's place, from 0.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "start": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it starts, in seconds.",
                                        "example": 0.0
                                      },
                                      "end": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it ends, in seconds.",
                                        "example": 600.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "Its title.",
                                        "example": "The First"
                                      }
                                    }
                                  },
                                  "description": "Chapters embedded in the file: none are read."
                                },
                                "embeddedCoverArt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "metaTags": {
                                  "type": "object",
                                  "description": "Tags read from the file: none until the stored media probe reads\nthem."
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The file's media type, such as `audio/mp4`.",
                                  "example": "audio/mp4"
                                }
                              }
                            },
                            "description": "The audio files, when fetched expanded."
                          },
                          "chapters": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "The chapters, when fetched expanded."
                          },
                          "tracks": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A track with its place in the book.",
                              "required": [
                                "index",
                                "startOffset",
                                "duration",
                                "title",
                                "contentUrl",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The track's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "startOffset": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where the track starts in the book, in seconds.",
                                  "example": 0.0
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The track's length in seconds.",
                                  "example": 36000.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "The track's title: its file name.",
                                  "example": "The First"
                                },
                                "contentUrl": {
                                  "type": "string",
                                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The track's media type.",
                                  "example": "audio/mp4"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "metadata": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "description": "The file's name, size and times.",
                                      "required": [
                                        "filename",
                                        "ext",
                                        "path",
                                        "relPath",
                                        "size",
                                        "mtimeMs",
                                        "ctimeMs",
                                        "birthtimeMs"
                                      ],
                                      "properties": {
                                        "filename": {
                                          "type": "string",
                                          "description": "The file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "ext": {
                                          "type": "string",
                                          "description": "The extension with its dot (`.m4b`).",
                                          "example": ".m4b"
                                        },
                                        "path": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "/the-first.m4b"
                                        },
                                        "relPath": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "size": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "The file's size in bytes.",
                                          "example": 100000,
                                          "minimum": 0
                                        },
                                        "mtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "ctimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "birthtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        }
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            },
                            "description": "The tracks with their place in the book, when fetched expanded."
                          }
                        }
                      },
                      "numFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Files in the item.",
                        "example": 1,
                        "minimum": 0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in all its files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "libraryFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A file of an item, in the expanded item's `libraryFiles`.",
                          "required": [
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "fileType"
                          ],
                          "properties": {
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "fileType": {
                              "type": "string",
                              "description": "Always `audio`.",
                              "example": "audio"
                            }
                          }
                        },
                        "description": "The item's files, when the item is fetched expanded."
                      },
                      "userMediaProgress": {
                        "oneOf": [
                          {
                            "type": "object",
                            "description": "The patron's progress, when the app asked for it.",
                            "required": [
                              "id",
                              "userId",
                              "libraryItemId",
                              "mediaItemId",
                              "mediaItemType",
                              "duration",
                              "progress",
                              "currentTime",
                              "isFinished",
                              "hideFromContinueListening",
                              "lastUpdate",
                              "startedAt"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The progress id: the item id (one record per patron and item).",
                                "example": "li_8f14e45fceea467f"
                              },
                              "userId": {
                                "type": "string",
                                "description": "The patron's id.",
                                "example": "42"
                              },
                              "libraryItemId": {
                                "type": "string",
                                "description": "The item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "episodeId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "mediaItemId": {
                                "type": "string",
                                "description": "The media id: the item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "mediaItemType": {
                                "type": "string",
                                "description": "Always `book`.",
                                "example": "book"
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The book's length in seconds, as last reported.",
                                "example": 36000.0
                              },
                              "progress": {
                                "type": "number",
                                "format": "double",
                                "description": "The share listened, from 0 to 1.",
                                "example": 0.05
                              },
                              "currentTime": {
                                "type": "number",
                                "format": "double",
                                "description": "Where the patron is, in seconds.",
                                "example": 1830.5
                              },
                              "isFinished": {
                                "type": "boolean",
                                "description": "Whether the patron finished it.",
                                "example": false
                              },
                              "hideFromContinueListening": {
                                "type": "boolean",
                                "description": "Whether it is hidden from continue listening.",
                                "example": false
                              },
                              "ebookLocation": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "ebookProgress": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "format": "double",
                                "description": "Always null.",
                                "example": null
                              },
                              "lastUpdate": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the progress last changed, in epoch milliseconds.",
                                "example": 1763630000000
                              },
                              "startedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the patron started, in epoch milliseconds.",
                                "example": 1763620000000
                              },
                              "finishedAt": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "When the patron finished, in epoch milliseconds.",
                                "example": null
                              }
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "seriesSequence": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item's place in a series, on a series' book list.",
                        "example": "1"
                      }
                    }
                  },
                  "description": "The items, in series order."
                }
              }
            },
            "description": "The author's series with their items, when asked for."
          }
        }
      },
      "description": "The authors."
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/narrators

Lists the library's narrators.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200Every narrator, by name (up to 5000). Body: Narrators (application/json)1 field
    • narratorsarray of NarratorrequiredThe narrators.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/narrators' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/narrators' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/narrators",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/narrators", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/narrators")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Every narrator, by name (up to 5000).

{
  "narrators": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author",
      "numBooks": 1
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/libraries/{id}/narrators`.",
  "required": [
    "narrators"
  ],
  "properties": {
    "narrators": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A narrator with how many items they read.",
        "required": [
          "id",
          "name",
          "numBooks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The name in URL-safe base64, as apps filter by it.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "The narrator's name.",
            "example": "Ann Author"
          },
          "numBooks": {
            "type": "integer",
            "format": "int64",
            "description": "Items they read that the patron can see.",
            "example": 1,
            "minimum": 0
          }
        }
      },
      "description": "The narrators."
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/collections

Lists the library's collections: none yet.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200An empty page. Body: EmptyPage (application/json)4 fields
    • resultsarray of objectrequiredAlways empty.
    • totalinteger (int64)requiredAlways 0. At least 0.
    • limitinteger (int64)requiredItems per page, echoed. At least 0.
    • pageinteger (int64)requiredThe page number, echoed. At least 0.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/collections' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/collections' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/collections",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/collections", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/collections")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: An empty page.

{
  "results": [],
  "total": 1,
  "limit": 20,
  "page": 0
}

Schema:

{
  "type": "object",
  "description": "An empty page, for collections and playlists the library does not\nhave yet.",
  "required": [
    "results",
    "total",
    "limit",
    "page"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Always empty.",
      "example": []
    },
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "Always 0.",
      "example": 1,
      "minimum": 0
    },
    "limit": {
      "type": "integer",
      "format": "int64",
      "description": "Items per page, echoed.",
      "example": 20,
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "format": "int64",
      "description": "The page number, echoed.",
      "example": 0,
      "minimum": 0
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/playlists

Lists the patron's playlists in the library: none yet.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200An empty page. Body: EmptyPage (application/json)4 fields
    • resultsarray of objectrequiredAlways empty.
    • totalinteger (int64)requiredAlways 0. At least 0.
    • limitinteger (int64)requiredItems per page, echoed. At least 0.
    • pageinteger (int64)requiredThe page number, echoed. At least 0.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/playlists' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/playlists' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/playlists",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/playlists", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/playlists")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: An empty page.

{
  "results": [],
  "total": 1,
  "limit": 20,
  "page": 0
}

Schema:

{
  "type": "object",
  "description": "An empty page, for collections and playlists the library does not\nhave yet.",
  "required": [
    "results",
    "total",
    "limit",
    "page"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Always empty.",
      "example": []
    },
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "Always 0.",
      "example": 1,
      "minimum": 0
    },
    "limit": {
      "type": "integer",
      "format": "int64",
      "description": "Items per page, echoed.",
      "example": 20,
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "format": "int64",
      "description": "The page number, echoed.",
      "example": 0,
      "minimum": 0
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/personalized

Reads the patron's home shelves: continue listening, recently added and listen again.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200The shelves that have items. Body: array of Shelf (application/json)6 fields
    • idstringrequiredThe shelf id, such as continue-listening.
    • labelstringrequiredThe shelf's English label.
    • labelStringKeystringrequiredThe key apps translate the label by.
    • typestringrequiredWhat the shelf holds: book, series or authors.
    • entitiesShelfEntitiesrequiredThe shelf's entries.
    • totalinteger (int64)requiredEntries in all. At least 0.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/personalized' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/personalized' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/personalized",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/personalized", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/personalized")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The shelves that have items.

[
  {
    "id": "li_8f14e45fceea467f",
    "label": "Continue Listening",
    "labelStringKey": "LabelContinueListening",
    "type": "user",
    "entities": [
      {
        "id": "li_8f14e45fceea467f",
        "ino": "0",
        "oldLibraryItemId": null,
        "libraryId": "bookclerk-library",
        "folderId": "bookclerk-library",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "isFile": true,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000,
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "id": "li_8f14e45fceea467f",
          "metadata": {
            "title": "The First",
            "titleIgnorePrefix": "First, The",
            "authors": [],
            "authorName": "Ann Author",
            "authorNameLF": "Author, Ann",
            "narrators": [
              "Nia Narrator"
            ],
            "narratorName": "Nia Narrator",
            "series": [],
            "seriesName": "The Saga #1",
            "genres": [
              "Fantasy"
            ],
            "explicit": false,
            "abridged": false
          },
          "tags": [],
          "numTracks": 1,
          "numAudioFiles": 1,
          "numChapters": 0,
          "duration": 36000.0,
          "size": 100000
        },
        "numFiles": 1,
        "size": 100000,
        "libraryFiles": [],
        "userMediaProgress": {
          "id": "li_8f14e45fceea467f",
          "userId": "42",
          "libraryItemId": "li_8f14e45fceea467f",
          "mediaItemId": "li_8f14e45fceea467f",
          "mediaItemType": "book",
          "duration": 36000.0,
          "progress": 0.05,
          "currentTime": 1830.5,
          "isFinished": false,
          "hideFromContinueListening": false,
          "lastUpdate": 1763630000000,
          "startedAt": 1763620000000
        },
        "seriesSequence": "1"
      }
    ],
    "total": 1
  }
]

Schema:

{
  "type": "array",
  "items": {
    "type": "object",
    "description": "A personalized shelf on the home screen.",
    "required": [
      "id",
      "label",
      "labelStringKey",
      "type",
      "entities",
      "total"
    ],
    "properties": {
      "id": {
        "type": "string",
        "description": "The shelf id, such as `continue-listening`.",
        "example": "li_8f14e45fceea467f"
      },
      "label": {
        "type": "string",
        "description": "The shelf's English label.",
        "example": "Continue Listening"
      },
      "labelStringKey": {
        "type": "string",
        "description": "The key apps translate the label by.",
        "example": "LabelContinueListening"
      },
      "type": {
        "type": "string",
        "description": "What the shelf holds: `book`, `series` or `authors`.",
        "example": "user"
      },
      "entities": {
        "oneOf": [
          {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "Items."
          },
          {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A series.",
              "required": [
                "id",
                "name",
                "nameIgnorePrefix",
                "addedAt",
                "updatedAt",
                "libraryId"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The series id.",
                  "example": "li_8f14e45fceea467f"
                },
                "name": {
                  "type": "string",
                  "description": "Its name.",
                  "example": "Ann Author"
                },
                "nameIgnorePrefix": {
                  "type": "string",
                  "description": "The name for sorting.",
                  "example": "Saga, The"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Its description: none.",
                  "example": "A short description."
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the library first saw it, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When it last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library it is listed in.",
                  "example": "bookclerk-library"
                },
                "books": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "An item: an edition with a stored copy.",
                    "required": [
                      "id",
                      "ino",
                      "libraryId",
                      "folderId",
                      "path",
                      "relPath",
                      "isFile",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs",
                      "addedAt",
                      "updatedAt",
                      "isMissing",
                      "isInvalid",
                      "mediaType",
                      "media",
                      "numFiles",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The item id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "ino": {
                        "type": "string",
                        "description": "The item's inode as apps expect one: the edition id again.",
                        "example": "0"
                      },
                      "oldLibraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "libraryId": {
                        "type": "string",
                        "description": "The library the item is listed in.",
                        "example": "bookclerk-library"
                      },
                      "folderId": {
                        "type": "string",
                        "description": "The folder id: the library id.",
                        "example": "bookclerk-library"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "the-first.m4b"
                      },
                      "isFile": {
                        "type": "boolean",
                        "description": "Always false: an item is a folder of tracks.",
                        "example": true
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy last changed, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the item joined the library, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When its record last changed, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "isMissing": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "isInvalid": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "mediaType": {
                        "type": "string",
                        "description": "Always [`MEDIA_TYPE_BOOK`].",
                        "example": "book"
                      },
                      "media": {
                        "type": "object",
                        "description": "The book.",
                        "required": [
                          "id",
                          "metadata",
                          "tags",
                          "numTracks",
                          "numAudioFiles",
                          "numChapters",
                          "duration",
                          "size"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The media id: the edition id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "libraryItemId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The item id, when fetched expanded.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The book's metadata.",
                            "required": [
                              "title",
                              "titleIgnorePrefix",
                              "authors",
                              "authorName",
                              "authorNameLF",
                              "narrators",
                              "narratorName",
                              "series",
                              "seriesName",
                              "genres",
                              "explicit",
                              "abridged"
                            ],
                            "properties": {
                              "title": {
                                "type": "string",
                                "description": "The title.",
                                "example": "The First"
                              },
                              "titleIgnorePrefix": {
                                "type": "string",
                                "description": "The title for sorting.",
                                "example": "First, The"
                              },
                              "subtitle": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The subtitle, if any.",
                                "example": "A Novel"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "An id and a name.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The entity's id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "Its display name.",
                                      "example": "Ann Author"
                                    }
                                  }
                                },
                                "description": "The authors."
                              },
                              "authorName": {
                                "type": "string",
                                "description": "The authors' names joined with `, `.",
                                "example": "Ann Author"
                              },
                              "authorNameLF": {
                                "type": "string",
                                "description": "The authors' names, family name first, joined with `, `.",
                                "example": "Author, Ann"
                              },
                              "narrators": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The narrators' names.",
                                "example": [
                                  "Nia Narrator"
                                ]
                              },
                              "narratorName": {
                                "type": "string",
                                "description": "The narrators' names joined with `, `.",
                                "example": "Nia Narrator"
                              },
                              "series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "A series an item belongs to, with the item's place in it.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The series id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "The series name.",
                                      "example": "Ann Author"
                                    },
                                    "sequence": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                      "example": "1"
                                    }
                                  }
                                },
                                "description": "The series the book is in."
                              },
                              "seriesName": {
                                "type": "string",
                                "description": "The series names with the book's place (`Name #2`), joined.",
                                "example": "The Saga #1"
                              },
                              "genres": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Genres.",
                                "example": [
                                  "Fantasy"
                                ]
                              },
                              "publishedYear": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The year of publication, as a string (`\"2019\"`).",
                                "example": "2024"
                              },
                              "publishedDate": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The date of publication, if known.",
                                "example": "2024-03-01"
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The publisher.",
                                "example": "Example Press"
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description, as the library stores it.",
                                "example": "A short description."
                              },
                              "descriptionPlain": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description with markup removed.",
                                "example": "A short description."
                              },
                              "isbn": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ISBN, if known.",
                                "example": "9780000000002"
                              },
                              "asin": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ASIN, if known.",
                                "example": "B000000000"
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The language.",
                                "example": "en-us"
                              },
                              "explicit": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "abridged": {
                                "type": "boolean",
                                "description": "Whether the edition is abridged.",
                                "example": false
                              }
                            }
                          },
                          "coverPath": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/cover"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Tags: none.",
                            "example": []
                          },
                          "numTracks": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Tracks in play order.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numAudioFiles": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Audio files.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numChapters": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Chapters.",
                            "example": 0,
                            "minimum": 0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds.",
                            "example": 36000.0
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Bytes in its audio files.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "audioFiles": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "An audio file of a book.",
                              "required": [
                                "index",
                                "ino",
                                "metadata",
                                "addedAt",
                                "updatedAt",
                                "manuallyVerified",
                                "exclude",
                                "duration",
                                "chapters",
                                "metaTags",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "ino": {
                                  "type": "string",
                                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                  "example": "0"
                                },
                                "metadata": {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                "addedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "updatedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763630000000
                                },
                                "trackNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number the file's tags state: not read.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "discNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number the file's tags state: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "trackNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "discNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "manuallyVerified": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "exclude": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "error": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "format": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The container format, such as `mp4` or `mp3`.",
                                  "example": "MP4A"
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The file's length in seconds.",
                                  "example": 36000.0
                                },
                                "bitRate": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Bits per second, if known.",
                                  "example": 128000,
                                  "minimum": 0
                                },
                                "language": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The file's language, if known.",
                                  "example": "en-us"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "timeBase": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The time base, if known.",
                                  "example": "1/44100"
                                },
                                "channels": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Audio channels, if known.",
                                  "example": 2,
                                  "minimum": 0
                                },
                                "channelLayout": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The channel layout, if known.",
                                  "example": "stereo"
                                },
                                "chapters": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "description": "A chapter of a book.",
                                    "required": [
                                      "id",
                                      "start",
                                      "end",
                                      "title"
                                    ],
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The chapter's place, from 0.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "start": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it starts, in seconds.",
                                        "example": 0.0
                                      },
                                      "end": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it ends, in seconds.",
                                        "example": 600.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "Its title.",
                                        "example": "The First"
                                      }
                                    }
                                  },
                                  "description": "Chapters embedded in the file: none are read."
                                },
                                "embeddedCoverArt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "metaTags": {
                                  "type": "object",
                                  "description": "Tags read from the file: none until the stored media probe reads\nthem."
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The file's media type, such as `audio/mp4`.",
                                  "example": "audio/mp4"
                                }
                              }
                            },
                            "description": "The audio files, when fetched expanded."
                          },
                          "chapters": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "The chapters, when fetched expanded."
                          },
                          "tracks": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A track with its place in the book.",
                              "required": [
                                "index",
                                "startOffset",
                                "duration",
                                "title",
                                "contentUrl",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The track's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "startOffset": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where the track starts in the book, in seconds.",
                                  "example": 0.0
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The track's length in seconds.",
                                  "example": 36000.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "The track's title: its file name.",
                                  "example": "The First"
                                },
                                "contentUrl": {
                                  "type": "string",
                                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The track's media type.",
                                  "example": "audio/mp4"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "metadata": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "description": "The file's name, size and times.",
                                      "required": [
                                        "filename",
                                        "ext",
                                        "path",
                                        "relPath",
                                        "size",
                                        "mtimeMs",
                                        "ctimeMs",
                                        "birthtimeMs"
                                      ],
                                      "properties": {
                                        "filename": {
                                          "type": "string",
                                          "description": "The file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "ext": {
                                          "type": "string",
                                          "description": "The extension with its dot (`.m4b`).",
                                          "example": ".m4b"
                                        },
                                        "path": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "/the-first.m4b"
                                        },
                                        "relPath": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "size": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "The file's size in bytes.",
                                          "example": 100000,
                                          "minimum": 0
                                        },
                                        "mtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "ctimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "birthtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        }
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            },
                            "description": "The tracks with their place in the book, when fetched expanded."
                          }
                        }
                      },
                      "numFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Files in the item.",
                        "example": 1,
                        "minimum": 0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in all its files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "libraryFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A file of an item, in the expanded item's `libraryFiles`.",
                          "required": [
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "fileType"
                          ],
                          "properties": {
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "fileType": {
                              "type": "string",
                              "description": "Always `audio`.",
                              "example": "audio"
                            }
                          }
                        },
                        "description": "The item's files, when the item is fetched expanded."
                      },
                      "userMediaProgress": {
                        "oneOf": [
                          {
                            "type": "object",
                            "description": "The patron's progress, when the app asked for it.",
                            "required": [
                              "id",
                              "userId",
                              "libraryItemId",
                              "mediaItemId",
                              "mediaItemType",
                              "duration",
                              "progress",
                              "currentTime",
                              "isFinished",
                              "hideFromContinueListening",
                              "lastUpdate",
                              "startedAt"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The progress id: the item id (one record per patron and item).",
                                "example": "li_8f14e45fceea467f"
                              },
                              "userId": {
                                "type": "string",
                                "description": "The patron's id.",
                                "example": "42"
                              },
                              "libraryItemId": {
                                "type": "string",
                                "description": "The item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "episodeId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "mediaItemId": {
                                "type": "string",
                                "description": "The media id: the item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "mediaItemType": {
                                "type": "string",
                                "description": "Always `book`.",
                                "example": "book"
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The book's length in seconds, as last reported.",
                                "example": 36000.0
                              },
                              "progress": {
                                "type": "number",
                                "format": "double",
                                "description": "The share listened, from 0 to 1.",
                                "example": 0.05
                              },
                              "currentTime": {
                                "type": "number",
                                "format": "double",
                                "description": "Where the patron is, in seconds.",
                                "example": 1830.5
                              },
                              "isFinished": {
                                "type": "boolean",
                                "description": "Whether the patron finished it.",
                                "example": false
                              },
                              "hideFromContinueListening": {
                                "type": "boolean",
                                "description": "Whether it is hidden from continue listening.",
                                "example": false
                              },
                              "ebookLocation": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "ebookProgress": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "format": "double",
                                "description": "Always null.",
                                "example": null
                              },
                              "lastUpdate": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the progress last changed, in epoch milliseconds.",
                                "example": 1763630000000
                              },
                              "startedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the patron started, in epoch milliseconds.",
                                "example": 1763620000000
                              },
                              "finishedAt": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "When the patron finished, in epoch milliseconds.",
                                "example": null
                              }
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "seriesSequence": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item's place in a series, on a series' book list.",
                        "example": "1"
                      }
                    }
                  },
                  "description": "Its items in series order, on lists."
                },
                "progress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress through it, when asked for.",
                      "required": [
                        "libraryItemIds",
                        "libraryItemIdsFinished",
                        "isFinished"
                      ],
                      "properties": {
                        "libraryItemIds": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The series' items, by id.",
                          "example": [
                            "li_8f14e45fceea467f"
                          ]
                        },
                        "libraryItemIdsFinished": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Those the patron finished.",
                          "example": []
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished every one.",
                          "example": false
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "Series."
          },
          {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An author.",
              "required": [
                "id",
                "name",
                "lastFirst",
                "libraryId",
                "addedAt",
                "updatedAt",
                "numBooks"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The contributor id.",
                  "example": "li_8f14e45fceea467f"
                },
                "asin": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": "B000000000"
                },
                "name": {
                  "type": "string",
                  "description": "The author's name.",
                  "example": "Ann Author"
                },
                "lastFirst": {
                  "type": "string",
                  "description": "The name family name first.",
                  "example": "Author, Ann"
                },
                "description": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": "A short description."
                },
                "imagePath": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null: no author images.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library it is listed in.",
                  "example": "bookclerk-library"
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the library first saw the author, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "numBooks": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Items by the author the patron can see.",
                  "example": 1,
                  "minimum": 0
                },
                "libraryItems": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "An item: an edition with a stored copy.",
                    "required": [
                      "id",
                      "ino",
                      "libraryId",
                      "folderId",
                      "path",
                      "relPath",
                      "isFile",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs",
                      "addedAt",
                      "updatedAt",
                      "isMissing",
                      "isInvalid",
                      "mediaType",
                      "media",
                      "numFiles",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The item id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "ino": {
                        "type": "string",
                        "description": "The item's inode as apps expect one: the edition id again.",
                        "example": "0"
                      },
                      "oldLibraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "libraryId": {
                        "type": "string",
                        "description": "The library the item is listed in.",
                        "example": "bookclerk-library"
                      },
                      "folderId": {
                        "type": "string",
                        "description": "The folder id: the library id.",
                        "example": "bookclerk-library"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "the-first.m4b"
                      },
                      "isFile": {
                        "type": "boolean",
                        "description": "Always false: an item is a folder of tracks.",
                        "example": true
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy last changed, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the item joined the library, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When its record last changed, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "isMissing": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "isInvalid": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "mediaType": {
                        "type": "string",
                        "description": "Always [`MEDIA_TYPE_BOOK`].",
                        "example": "book"
                      },
                      "media": {
                        "type": "object",
                        "description": "The book.",
                        "required": [
                          "id",
                          "metadata",
                          "tags",
                          "numTracks",
                          "numAudioFiles",
                          "numChapters",
                          "duration",
                          "size"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The media id: the edition id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "libraryItemId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The item id, when fetched expanded.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The book's metadata.",
                            "required": [
                              "title",
                              "titleIgnorePrefix",
                              "authors",
                              "authorName",
                              "authorNameLF",
                              "narrators",
                              "narratorName",
                              "series",
                              "seriesName",
                              "genres",
                              "explicit",
                              "abridged"
                            ],
                            "properties": {
                              "title": {
                                "type": "string",
                                "description": "The title.",
                                "example": "The First"
                              },
                              "titleIgnorePrefix": {
                                "type": "string",
                                "description": "The title for sorting.",
                                "example": "First, The"
                              },
                              "subtitle": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The subtitle, if any.",
                                "example": "A Novel"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "An id and a name.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The entity's id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "Its display name.",
                                      "example": "Ann Author"
                                    }
                                  }
                                },
                                "description": "The authors."
                              },
                              "authorName": {
                                "type": "string",
                                "description": "The authors' names joined with `, `.",
                                "example": "Ann Author"
                              },
                              "authorNameLF": {
                                "type": "string",
                                "description": "The authors' names, family name first, joined with `, `.",
                                "example": "Author, Ann"
                              },
                              "narrators": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The narrators' names.",
                                "example": [
                                  "Nia Narrator"
                                ]
                              },
                              "narratorName": {
                                "type": "string",
                                "description": "The narrators' names joined with `, `.",
                                "example": "Nia Narrator"
                              },
                              "series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "A series an item belongs to, with the item's place in it.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The series id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "The series name.",
                                      "example": "Ann Author"
                                    },
                                    "sequence": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                      "example": "1"
                                    }
                                  }
                                },
                                "description": "The series the book is in."
                              },
                              "seriesName": {
                                "type": "string",
                                "description": "The series names with the book's place (`Name #2`), joined.",
                                "example": "The Saga #1"
                              },
                              "genres": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Genres.",
                                "example": [
                                  "Fantasy"
                                ]
                              },
                              "publishedYear": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The year of publication, as a string (`\"2019\"`).",
                                "example": "2024"
                              },
                              "publishedDate": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The date of publication, if known.",
                                "example": "2024-03-01"
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The publisher.",
                                "example": "Example Press"
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description, as the library stores it.",
                                "example": "A short description."
                              },
                              "descriptionPlain": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description with markup removed.",
                                "example": "A short description."
                              },
                              "isbn": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ISBN, if known.",
                                "example": "9780000000002"
                              },
                              "asin": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ASIN, if known.",
                                "example": "B000000000"
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The language.",
                                "example": "en-us"
                              },
                              "explicit": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "abridged": {
                                "type": "boolean",
                                "description": "Whether the edition is abridged.",
                                "example": false
                              }
                            }
                          },
                          "coverPath": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/cover"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Tags: none.",
                            "example": []
                          },
                          "numTracks": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Tracks in play order.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numAudioFiles": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Audio files.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numChapters": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Chapters.",
                            "example": 0,
                            "minimum": 0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds.",
                            "example": 36000.0
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Bytes in its audio files.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "audioFiles": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "An audio file of a book.",
                              "required": [
                                "index",
                                "ino",
                                "metadata",
                                "addedAt",
                                "updatedAt",
                                "manuallyVerified",
                                "exclude",
                                "duration",
                                "chapters",
                                "metaTags",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "ino": {
                                  "type": "string",
                                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                  "example": "0"
                                },
                                "metadata": {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                "addedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "updatedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763630000000
                                },
                                "trackNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number the file's tags state: not read.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "discNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number the file's tags state: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "trackNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "discNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "manuallyVerified": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "exclude": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "error": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "format": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The container format, such as `mp4` or `mp3`.",
                                  "example": "MP4A"
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The file's length in seconds.",
                                  "example": 36000.0
                                },
                                "bitRate": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Bits per second, if known.",
                                  "example": 128000,
                                  "minimum": 0
                                },
                                "language": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The file's language, if known.",
                                  "example": "en-us"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "timeBase": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The time base, if known.",
                                  "example": "1/44100"
                                },
                                "channels": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Audio channels, if known.",
                                  "example": 2,
                                  "minimum": 0
                                },
                                "channelLayout": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The channel layout, if known.",
                                  "example": "stereo"
                                },
                                "chapters": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "description": "A chapter of a book.",
                                    "required": [
                                      "id",
                                      "start",
                                      "end",
                                      "title"
                                    ],
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The chapter's place, from 0.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "start": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it starts, in seconds.",
                                        "example": 0.0
                                      },
                                      "end": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it ends, in seconds.",
                                        "example": 600.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "Its title.",
                                        "example": "The First"
                                      }
                                    }
                                  },
                                  "description": "Chapters embedded in the file: none are read."
                                },
                                "embeddedCoverArt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "metaTags": {
                                  "type": "object",
                                  "description": "Tags read from the file: none until the stored media probe reads\nthem."
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The file's media type, such as `audio/mp4`.",
                                  "example": "audio/mp4"
                                }
                              }
                            },
                            "description": "The audio files, when fetched expanded."
                          },
                          "chapters": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "The chapters, when fetched expanded."
                          },
                          "tracks": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A track with its place in the book.",
                              "required": [
                                "index",
                                "startOffset",
                                "duration",
                                "title",
                                "contentUrl",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The track's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "startOffset": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where the track starts in the book, in seconds.",
                                  "example": 0.0
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The track's length in seconds.",
                                  "example": 36000.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "The track's title: its file name.",
                                  "example": "The First"
                                },
                                "contentUrl": {
                                  "type": "string",
                                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The track's media type.",
                                  "example": "audio/mp4"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "metadata": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "description": "The file's name, size and times.",
                                      "required": [
                                        "filename",
                                        "ext",
                                        "path",
                                        "relPath",
                                        "size",
                                        "mtimeMs",
                                        "ctimeMs",
                                        "birthtimeMs"
                                      ],
                                      "properties": {
                                        "filename": {
                                          "type": "string",
                                          "description": "The file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "ext": {
                                          "type": "string",
                                          "description": "The extension with its dot (`.m4b`).",
                                          "example": ".m4b"
                                        },
                                        "path": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "/the-first.m4b"
                                        },
                                        "relPath": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "size": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "The file's size in bytes.",
                                          "example": 100000,
                                          "minimum": 0
                                        },
                                        "mtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "ctimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "birthtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        }
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            },
                            "description": "The tracks with their place in the book, when fetched expanded."
                          }
                        }
                      },
                      "numFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Files in the item.",
                        "example": 1,
                        "minimum": 0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in all its files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "libraryFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A file of an item, in the expanded item's `libraryFiles`.",
                          "required": [
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "fileType"
                          ],
                          "properties": {
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "fileType": {
                              "type": "string",
                              "description": "Always `audio`.",
                              "example": "audio"
                            }
                          }
                        },
                        "description": "The item's files, when the item is fetched expanded."
                      },
                      "userMediaProgress": {
                        "oneOf": [
                          {
                            "type": "object",
                            "description": "The patron's progress, when the app asked for it.",
                            "required": [
                              "id",
                              "userId",
                              "libraryItemId",
                              "mediaItemId",
                              "mediaItemType",
                              "duration",
                              "progress",
                              "currentTime",
                              "isFinished",
                              "hideFromContinueListening",
                              "lastUpdate",
                              "startedAt"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The progress id: the item id (one record per patron and item).",
                                "example": "li_8f14e45fceea467f"
                              },
                              "userId": {
                                "type": "string",
                                "description": "The patron's id.",
                                "example": "42"
                              },
                              "libraryItemId": {
                                "type": "string",
                                "description": "The item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "episodeId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "mediaItemId": {
                                "type": "string",
                                "description": "The media id: the item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "mediaItemType": {
                                "type": "string",
                                "description": "Always `book`.",
                                "example": "book"
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The book's length in seconds, as last reported.",
                                "example": 36000.0
                              },
                              "progress": {
                                "type": "number",
                                "format": "double",
                                "description": "The share listened, from 0 to 1.",
                                "example": 0.05
                              },
                              "currentTime": {
                                "type": "number",
                                "format": "double",
                                "description": "Where the patron is, in seconds.",
                                "example": 1830.5
                              },
                              "isFinished": {
                                "type": "boolean",
                                "description": "Whether the patron finished it.",
                                "example": false
                              },
                              "hideFromContinueListening": {
                                "type": "boolean",
                                "description": "Whether it is hidden from continue listening.",
                                "example": false
                              },
                              "ebookLocation": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "ebookProgress": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "format": "double",
                                "description": "Always null.",
                                "example": null
                              },
                              "lastUpdate": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the progress last changed, in epoch milliseconds.",
                                "example": 1763630000000
                              },
                              "startedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the patron started, in epoch milliseconds.",
                                "example": 1763620000000
                              },
                              "finishedAt": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "When the patron finished, in epoch milliseconds.",
                                "example": null
                              }
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "seriesSequence": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item's place in a series, on a series' book list.",
                        "example": "1"
                      }
                    }
                  },
                  "description": "The author's items, when asked for."
                },
                "series": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A series of an author's, with the author's items in it.",
                    "required": [
                      "id",
                      "name",
                      "items"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The series id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "name": {
                        "type": "string",
                        "description": "The series name.",
                        "example": "Ann Author"
                      },
                      "items": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "description": "An item: an edition with a stored copy.",
                          "required": [
                            "id",
                            "ino",
                            "libraryId",
                            "folderId",
                            "path",
                            "relPath",
                            "isFile",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs",
                            "addedAt",
                            "updatedAt",
                            "isMissing",
                            "isInvalid",
                            "mediaType",
                            "media",
                            "numFiles",
                            "size"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "The item id: the edition id.",
                              "example": "li_8f14e45fceea467f"
                            },
                            "ino": {
                              "type": "string",
                              "description": "The item's inode as apps expect one: the edition id again.",
                              "example": "0"
                            },
                            "oldLibraryItemId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "libraryId": {
                              "type": "string",
                              "description": "The library the item is listed in.",
                              "example": "bookclerk-library"
                            },
                            "folderId": {
                              "type": "string",
                              "description": "The folder id: the library id.",
                              "example": "bookclerk-library"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the title.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the title.",
                              "example": "the-first.m4b"
                            },
                            "isFile": {
                              "type": "boolean",
                              "description": "Always false: an item is a folder of tracks.",
                              "example": true
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the copy last changed, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the copy was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the copy was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the item joined the library, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When its record last changed, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "isMissing": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "isInvalid": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "mediaType": {
                              "type": "string",
                              "description": "Always [`MEDIA_TYPE_BOOK`].",
                              "example": "book"
                            },
                            "media": {
                              "type": "object",
                              "description": "The book.",
                              "required": [
                                "id",
                                "metadata",
                                "tags",
                                "numTracks",
                                "numAudioFiles",
                                "numChapters",
                                "duration",
                                "size"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The media id: the edition id.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "libraryItemId": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The item id, when fetched expanded.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "metadata": {
                                  "type": "object",
                                  "description": "The book's metadata.",
                                  "required": [
                                    "title",
                                    "titleIgnorePrefix",
                                    "authors",
                                    "authorName",
                                    "authorNameLF",
                                    "narrators",
                                    "narratorName",
                                    "series",
                                    "seriesName",
                                    "genres",
                                    "explicit",
                                    "abridged"
                                  ],
                                  "properties": {
                                    "title": {
                                      "type": "string",
                                      "description": "The title.",
                                      "example": "The First"
                                    },
                                    "titleIgnorePrefix": {
                                      "type": "string",
                                      "description": "The title for sorting.",
                                      "example": "First, The"
                                    },
                                    "subtitle": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The subtitle, if any.",
                                      "example": "A Novel"
                                    },
                                    "authors": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "description": "An id and a name.",
                                        "required": [
                                          "id",
                                          "name"
                                        ],
                                        "properties": {
                                          "id": {
                                            "type": "string",
                                            "description": "The entity's id.",
                                            "example": "li_8f14e45fceea467f"
                                          },
                                          "name": {
                                            "type": "string",
                                            "description": "Its display name.",
                                            "example": "Ann Author"
                                          }
                                        }
                                      },
                                      "description": "The authors."
                                    },
                                    "authorName": {
                                      "type": "string",
                                      "description": "The authors' names joined with `, `.",
                                      "example": "Ann Author"
                                    },
                                    "authorNameLF": {
                                      "type": "string",
                                      "description": "The authors' names, family name first, joined with `, `.",
                                      "example": "Author, Ann"
                                    },
                                    "narrators": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      },
                                      "description": "The narrators' names.",
                                      "example": [
                                        "Nia Narrator"
                                      ]
                                    },
                                    "narratorName": {
                                      "type": "string",
                                      "description": "The narrators' names joined with `, `.",
                                      "example": "Nia Narrator"
                                    },
                                    "series": {
                                      "type": "array",
                                      "items": {
                                        "type": "object",
                                        "description": "A series an item belongs to, with the item's place in it.",
                                        "required": [
                                          "id",
                                          "name"
                                        ],
                                        "properties": {
                                          "id": {
                                            "type": "string",
                                            "description": "The series id.",
                                            "example": "li_8f14e45fceea467f"
                                          },
                                          "name": {
                                            "type": "string",
                                            "description": "The series name.",
                                            "example": "Ann Author"
                                          },
                                          "sequence": {
                                            "type": [
                                              "string",
                                              "null"
                                            ],
                                            "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                            "example": "1"
                                          }
                                        }
                                      },
                                      "description": "The series the book is in."
                                    },
                                    "seriesName": {
                                      "type": "string",
                                      "description": "The series names with the book's place (`Name #2`), joined.",
                                      "example": "The Saga #1"
                                    },
                                    "genres": {
                                      "type": "array",
                                      "items": {
                                        "type": "string"
                                      },
                                      "description": "Genres.",
                                      "example": [
                                        "Fantasy"
                                      ]
                                    },
                                    "publishedYear": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The year of publication, as a string (`\"2019\"`).",
                                      "example": "2024"
                                    },
                                    "publishedDate": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The date of publication, if known.",
                                      "example": "2024-03-01"
                                    },
                                    "publisher": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The publisher.",
                                      "example": "Example Press"
                                    },
                                    "description": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The description, as the library stores it.",
                                      "example": "A short description."
                                    },
                                    "descriptionPlain": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The description with markup removed.",
                                      "example": "A short description."
                                    },
                                    "isbn": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The ISBN, if known.",
                                      "example": "9780000000002"
                                    },
                                    "asin": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The ASIN, if known.",
                                      "example": "B000000000"
                                    },
                                    "language": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The language.",
                                      "example": "en-us"
                                    },
                                    "explicit": {
                                      "type": "boolean",
                                      "description": "Always false.",
                                      "example": false
                                    },
                                    "abridged": {
                                      "type": "boolean",
                                      "description": "Whether the edition is abridged.",
                                      "example": false
                                    }
                                  }
                                },
                                "coverPath": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                                  "example": "/player/api/items/li_8f14e45fceea467f/cover"
                                },
                                "tags": {
                                  "type": "array",
                                  "items": {
                                    "type": "string"
                                  },
                                  "description": "Tags: none.",
                                  "example": []
                                },
                                "numTracks": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "Tracks in play order.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "numAudioFiles": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "Audio files.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "numChapters": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "Chapters.",
                                  "example": 0,
                                  "minimum": 0
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The book's length in seconds.",
                                  "example": 36000.0
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "Bytes in its audio files.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "audioFiles": {
                                  "type": [
                                    "array",
                                    "null"
                                  ],
                                  "items": {
                                    "type": "object",
                                    "description": "An audio file of a book.",
                                    "required": [
                                      "index",
                                      "ino",
                                      "metadata",
                                      "addedAt",
                                      "updatedAt",
                                      "manuallyVerified",
                                      "exclude",
                                      "duration",
                                      "chapters",
                                      "metaTags",
                                      "mimeType"
                                    ],
                                    "properties": {
                                      "index": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The file's place in play order, from 1.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "ino": {
                                        "type": "string",
                                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                        "example": "0"
                                      },
                                      "metadata": {
                                        "type": "object",
                                        "description": "The file's name, size and times.",
                                        "required": [
                                          "filename",
                                          "ext",
                                          "path",
                                          "relPath",
                                          "size",
                                          "mtimeMs",
                                          "ctimeMs",
                                          "birthtimeMs"
                                        ],
                                        "properties": {
                                          "filename": {
                                            "type": "string",
                                            "description": "The file name.",
                                            "example": "the-first.m4b"
                                          },
                                          "ext": {
                                            "type": "string",
                                            "description": "The extension with its dot (`.m4b`).",
                                            "example": ".m4b"
                                          },
                                          "path": {
                                            "type": "string",
                                            "description": "A display path: the file name.",
                                            "example": "/the-first.m4b"
                                          },
                                          "relPath": {
                                            "type": "string",
                                            "description": "A display path: the file name.",
                                            "example": "the-first.m4b"
                                          },
                                          "size": {
                                            "type": "integer",
                                            "format": "int64",
                                            "description": "The file's size in bytes.",
                                            "example": 100000,
                                            "minimum": 0
                                          },
                                          "mtimeMs": {
                                            "type": "integer",
                                            "format": "int64",
                                            "description": "When the file was stored, in epoch milliseconds.",
                                            "example": 1763600000000
                                          },
                                          "ctimeMs": {
                                            "type": "integer",
                                            "format": "int64",
                                            "description": "When the file was stored, in epoch milliseconds.",
                                            "example": 1763600000000
                                          },
                                          "birthtimeMs": {
                                            "type": "integer",
                                            "format": "int64",
                                            "description": "When the file was stored, in epoch milliseconds.",
                                            "example": 1763600000000
                                          }
                                        }
                                      },
                                      "addedAt": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      },
                                      "updatedAt": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763630000000
                                      },
                                      "trackNumFromMeta": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "The track number the file's tags state: not read.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "discNumFromMeta": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "The disc number the file's tags state: not read.",
                                        "example": null,
                                        "minimum": 0
                                      },
                                      "trackNumFromFilename": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "The track number in the file name: not read.",
                                        "example": null,
                                        "minimum": 0
                                      },
                                      "discNumFromFilename": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "The disc number in the file name: not read.",
                                        "example": null,
                                        "minimum": 0
                                      },
                                      "manuallyVerified": {
                                        "type": "boolean",
                                        "description": "Always false.",
                                        "example": false
                                      },
                                      "exclude": {
                                        "type": "boolean",
                                        "description": "Always false.",
                                        "example": false
                                      },
                                      "error": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "Always null.",
                                        "example": null
                                      },
                                      "format": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The container format, such as `mp4` or `mp3`.",
                                        "example": "MP4A"
                                      },
                                      "duration": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "The file's length in seconds.",
                                        "example": 36000.0
                                      },
                                      "bitRate": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "Bits per second, if known.",
                                        "example": 128000,
                                        "minimum": 0
                                      },
                                      "language": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The file's language, if known.",
                                        "example": "en-us"
                                      },
                                      "codec": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The codec, if known.",
                                        "example": "aac"
                                      },
                                      "timeBase": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The time base, if known.",
                                        "example": "1/44100"
                                      },
                                      "channels": {
                                        "type": [
                                          "integer",
                                          "null"
                                        ],
                                        "format": "int64",
                                        "description": "Audio channels, if known.",
                                        "example": 2,
                                        "minimum": 0
                                      },
                                      "channelLayout": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The channel layout, if known.",
                                        "example": "stereo"
                                      },
                                      "chapters": {
                                        "type": "array",
                                        "items": {
                                          "type": "object",
                                          "description": "A chapter of a book.",
                                          "required": [
                                            "id",
                                            "start",
                                            "end",
                                            "title"
                                          ],
                                          "properties": {
                                            "id": {
                                              "type": "integer",
                                              "format": "int64",
                                              "description": "The chapter's place, from 0.",
                                              "example": 1,
                                              "minimum": 0
                                            },
                                            "start": {
                                              "type": "number",
                                              "format": "double",
                                              "description": "Where it starts, in seconds.",
                                              "example": 0.0
                                            },
                                            "end": {
                                              "type": "number",
                                              "format": "double",
                                              "description": "Where it ends, in seconds.",
                                              "example": 600.0
                                            },
                                            "title": {
                                              "type": "string",
                                              "description": "Its title.",
                                              "example": "The First"
                                            }
                                          }
                                        },
                                        "description": "Chapters embedded in the file: none are read."
                                      },
                                      "embeddedCoverArt": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "Always null.",
                                        "example": null
                                      },
                                      "metaTags": {
                                        "type": "object",
                                        "description": "Tags read from the file: none until the stored media probe reads\nthem."
                                      },
                                      "mimeType": {
                                        "type": "string",
                                        "description": "The file's media type, such as `audio/mp4`.",
                                        "example": "audio/mp4"
                                      }
                                    }
                                  },
                                  "description": "The audio files, when fetched expanded."
                                },
                                "chapters": {
                                  "type": [
                                    "array",
                                    "null"
                                  ],
                                  "items": {
                                    "type": "object",
                                    "description": "A chapter of a book.",
                                    "required": [
                                      "id",
                                      "start",
                                      "end",
                                      "title"
                                    ],
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The chapter's place, from 0.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "start": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it starts, in seconds.",
                                        "example": 0.0
                                      },
                                      "end": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it ends, in seconds.",
                                        "example": 600.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "Its title.",
                                        "example": "The First"
                                      }
                                    }
                                  },
                                  "description": "The chapters, when fetched expanded."
                                },
                                "tracks": {
                                  "type": [
                                    "array",
                                    "null"
                                  ],
                                  "items": {
                                    "type": "object",
                                    "description": "A track with its place in the book.",
                                    "required": [
                                      "index",
                                      "startOffset",
                                      "duration",
                                      "title",
                                      "contentUrl",
                                      "mimeType"
                                    ],
                                    "properties": {
                                      "index": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The track's place in play order, from 1.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "startOffset": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where the track starts in the book, in seconds.",
                                        "example": 0.0
                                      },
                                      "duration": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "The track's length in seconds.",
                                        "example": 36000.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "The track's title: its file name.",
                                        "example": "The First"
                                      },
                                      "contentUrl": {
                                        "type": "string",
                                        "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                        "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                                      },
                                      "mimeType": {
                                        "type": "string",
                                        "description": "The track's media type.",
                                        "example": "audio/mp4"
                                      },
                                      "codec": {
                                        "type": [
                                          "string",
                                          "null"
                                        ],
                                        "description": "The codec, if known.",
                                        "example": "aac"
                                      },
                                      "metadata": {
                                        "oneOf": [
                                          {
                                            "type": "object",
                                            "description": "The file's name, size and times.",
                                            "required": [
                                              "filename",
                                              "ext",
                                              "path",
                                              "relPath",
                                              "size",
                                              "mtimeMs",
                                              "ctimeMs",
                                              "birthtimeMs"
                                            ],
                                            "properties": {
                                              "filename": {
                                                "type": "string",
                                                "description": "The file name.",
                                                "example": "the-first.m4b"
                                              },
                                              "ext": {
                                                "type": "string",
                                                "description": "The extension with its dot (`.m4b`).",
                                                "example": ".m4b"
                                              },
                                              "path": {
                                                "type": "string",
                                                "description": "A display path: the file name.",
                                                "example": "/the-first.m4b"
                                              },
                                              "relPath": {
                                                "type": "string",
                                                "description": "A display path: the file name.",
                                                "example": "the-first.m4b"
                                              },
                                              "size": {
                                                "type": "integer",
                                                "format": "int64",
                                                "description": "The file's size in bytes.",
                                                "example": 100000,
                                                "minimum": 0
                                              },
                                              "mtimeMs": {
                                                "type": "integer",
                                                "format": "int64",
                                                "description": "When the file was stored, in epoch milliseconds.",
                                                "example": 1763600000000
                                              },
                                              "ctimeMs": {
                                                "type": "integer",
                                                "format": "int64",
                                                "description": "When the file was stored, in epoch milliseconds.",
                                                "example": 1763600000000
                                              },
                                              "birthtimeMs": {
                                                "type": "integer",
                                                "format": "int64",
                                                "description": "When the file was stored, in epoch milliseconds.",
                                                "example": 1763600000000
                                              }
                                            }
                                          },
                                          {
                                            "type": "null"
                                          }
                                        ]
                                      }
                                    }
                                  },
                                  "description": "The tracks with their place in the book, when fetched expanded."
                                }
                              }
                            },
                            "numFiles": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Files in the item.",
                              "example": 1,
                              "minimum": 0
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "Bytes in all its files.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "libraryFiles": {
                              "type": [
                                "array",
                                "null"
                              ],
                              "items": {
                                "type": "object",
                                "description": "A file of an item, in the expanded item's `libraryFiles`.",
                                "required": [
                                  "ino",
                                  "metadata",
                                  "addedAt",
                                  "updatedAt",
                                  "fileType"
                                ],
                                "properties": {
                                  "ino": {
                                    "type": "string",
                                    "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                    "example": "0"
                                  },
                                  "metadata": {
                                    "type": "object",
                                    "description": "The file's name, size and times.",
                                    "required": [
                                      "filename",
                                      "ext",
                                      "path",
                                      "relPath",
                                      "size",
                                      "mtimeMs",
                                      "ctimeMs",
                                      "birthtimeMs"
                                    ],
                                    "properties": {
                                      "filename": {
                                        "type": "string",
                                        "description": "The file name.",
                                        "example": "the-first.m4b"
                                      },
                                      "ext": {
                                        "type": "string",
                                        "description": "The extension with its dot (`.m4b`).",
                                        "example": ".m4b"
                                      },
                                      "path": {
                                        "type": "string",
                                        "description": "A display path: the file name.",
                                        "example": "/the-first.m4b"
                                      },
                                      "relPath": {
                                        "type": "string",
                                        "description": "A display path: the file name.",
                                        "example": "the-first.m4b"
                                      },
                                      "size": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The file's size in bytes.",
                                        "example": 100000,
                                        "minimum": 0
                                      },
                                      "mtimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      },
                                      "ctimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      },
                                      "birthtimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      }
                                    }
                                  },
                                  "addedAt": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "updatedAt": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763630000000
                                  },
                                  "fileType": {
                                    "type": "string",
                                    "description": "Always `audio`.",
                                    "example": "audio"
                                  }
                                }
                              },
                              "description": "The item's files, when the item is fetched expanded."
                            },
                            "userMediaProgress": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "description": "The patron's progress, when the app asked for it.",
                                  "required": [
                                    "id",
                                    "userId",
                                    "libraryItemId",
                                    "mediaItemId",
                                    "mediaItemType",
                                    "duration",
                                    "progress",
                                    "currentTime",
                                    "isFinished",
                                    "hideFromContinueListening",
                                    "lastUpdate",
                                    "startedAt"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The progress id: the item id (one record per patron and item).",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "userId": {
                                      "type": "string",
                                      "description": "The patron's id.",
                                      "example": "42"
                                    },
                                    "libraryItemId": {
                                      "type": "string",
                                      "description": "The item id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "episodeId": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "Always null.",
                                      "example": null
                                    },
                                    "mediaItemId": {
                                      "type": "string",
                                      "description": "The media id: the item id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "mediaItemType": {
                                      "type": "string",
                                      "description": "Always `book`.",
                                      "example": "book"
                                    },
                                    "duration": {
                                      "type": "number",
                                      "format": "double",
                                      "description": "The book's length in seconds, as last reported.",
                                      "example": 36000.0
                                    },
                                    "progress": {
                                      "type": "number",
                                      "format": "double",
                                      "description": "The share listened, from 0 to 1.",
                                      "example": 0.05
                                    },
                                    "currentTime": {
                                      "type": "number",
                                      "format": "double",
                                      "description": "Where the patron is, in seconds.",
                                      "example": 1830.5
                                    },
                                    "isFinished": {
                                      "type": "boolean",
                                      "description": "Whether the patron finished it.",
                                      "example": false
                                    },
                                    "hideFromContinueListening": {
                                      "type": "boolean",
                                      "description": "Whether it is hidden from continue listening.",
                                      "example": false
                                    },
                                    "ebookLocation": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "Always null.",
                                      "example": null
                                    },
                                    "ebookProgress": {
                                      "type": [
                                        "number",
                                        "null"
                                      ],
                                      "format": "double",
                                      "description": "Always null.",
                                      "example": null
                                    },
                                    "lastUpdate": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the progress last changed, in epoch milliseconds.",
                                      "example": 1763630000000
                                    },
                                    "startedAt": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the patron started, in epoch milliseconds.",
                                      "example": 1763620000000
                                    },
                                    "finishedAt": {
                                      "type": [
                                        "integer",
                                        "null"
                                      ],
                                      "format": "int64",
                                      "description": "When the patron finished, in epoch milliseconds.",
                                      "example": null
                                    }
                                  }
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            },
                            "seriesSequence": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The item's place in a series, on a series' book list.",
                              "example": "1"
                            }
                          }
                        },
                        "description": "The items, in series order."
                      }
                    }
                  },
                  "description": "The author's series with their items, when asked for."
                }
              }
            },
            "description": "Authors."
          }
        ],
        "description": "The shelf's entries."
      },
      "total": {
        "type": "integer",
        "format": "int64",
        "description": "Entries in all.",
        "example": 1,
        "minimum": 0
      }
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/search

Searches the library's items, series, authors and narrators.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.
  • qquerystringrequiredThe search terms.
  • limitqueryinteger (int64)Matches of each kind, default 12.

Responses

  • 200The matches. Body: SearchResults (application/json)7 fields
    • bookarray of SearchBookrequiredMatching items.
    • podcastarray of objectrequiredAlways empty.
    • narratorsarray of NarratorrequiredMatching narrators.
    • tagsarray of objectrequiredAlways empty.
    • genresarray of objectrequiredAlways empty.
    • seriesarray of SearchSeriesrequiredMatching series.
    • authorsarray of AuthorrequiredMatching authors.
  • 400A query value is out of range, or the terms do not parse. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The search index is being built; retry. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/search?q=string")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The matches.

{
  "book": [
    {
      "libraryItem": {
        "id": "li_8f14e45fceea467f",
        "ino": "0",
        "oldLibraryItemId": null,
        "libraryId": "bookclerk-library",
        "folderId": "bookclerk-library",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "isFile": true,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000,
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "id": "li_8f14e45fceea467f",
          "metadata": {
            "title": "The First",
            "titleIgnorePrefix": "First, The",
            "authors": [],
            "authorName": "Ann Author",
            "authorNameLF": "Author, Ann",
            "narrators": [
              "Nia Narrator"
            ],
            "narratorName": "Nia Narrator",
            "series": [],
            "seriesName": "The Saga #1",
            "genres": [
              "Fantasy"
            ],
            "explicit": false,
            "abridged": false
          },
          "tags": [],
          "numTracks": 1,
          "numAudioFiles": 1,
          "numChapters": 0,
          "duration": 36000.0,
          "size": 100000
        },
        "numFiles": 1,
        "size": 100000,
        "libraryFiles": [],
        "userMediaProgress": {
          "id": "li_8f14e45fceea467f",
          "userId": "42",
          "libraryItemId": "li_8f14e45fceea467f",
          "mediaItemId": "li_8f14e45fceea467f",
          "mediaItemType": "book",
          "duration": 36000.0,
          "progress": 0.05,
          "currentTime": 1830.5,
          "isFinished": false,
          "hideFromContinueListening": false,
          "lastUpdate": 1763630000000,
          "startedAt": 1763620000000
        },
        "seriesSequence": "1"
      }
    }
  ],
  "podcast": [],
  "narrators": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author",
      "numBooks": 1
    }
  ],
  "tags": [],
  "genres": [],
  "series": [
    {
      "series": {
        "id": "li_8f14e45fceea467f",
        "name": "Ann Author",
        "nameIgnorePrefix": "Saga, The",
        "description": "A short description.",
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "libraryId": "bookclerk-library",
        "books": [],
        "progress": {
          "libraryItemIds": [
            "li_8f14e45fceea467f"
          ],
          "libraryItemIdsFinished": [],
          "isFinished": false
        }
      },
      "books": [
        {
          "id": "li_8f14e45fceea467f",
          "ino": "0",
          "libraryId": "bookclerk-library",
          "folderId": "bookclerk-library",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "isFile": true,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000,
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "id": "li_8f14e45fceea467f",
            "metadata": {
              "title": "The First",
              "titleIgnorePrefix": "First, The",
              "authors": [],
              "authorName": "Ann Author",
              "authorNameLF": "Author, Ann",
              "narrators": [
                "Nia Narrator"
              ],
              "narratorName": "Nia Narrator",
              "series": [],
              "seriesName": "The Saga #1",
              "genres": [
                "Fantasy"
              ],
              "explicit": false,
              "abridged": false
            },
            "tags": [],
            "numTracks": 1,
            "numAudioFiles": 1,
            "numChapters": 0,
            "duration": 36000.0,
            "size": 100000
          },
          "numFiles": 1,
          "size": 100000
        }
      ]
    }
  ],
  "authors": [
    {
      "id": "li_8f14e45fceea467f",
      "asin": "B000000000",
      "name": "Ann Author",
      "lastFirst": "Author, Ann",
      "description": "A short description.",
      "imagePath": null,
      "libraryId": "bookclerk-library",
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "numBooks": 1,
      "libraryItems": [
        {
          "id": "li_8f14e45fceea467f",
          "ino": "0",
          "libraryId": "bookclerk-library",
          "folderId": "bookclerk-library",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "isFile": true,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000,
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "id": "li_8f14e45fceea467f",
            "metadata": {
              "title": "The First",
              "titleIgnorePrefix": "First, The",
              "authors": [],
              "authorName": "Ann Author",
              "authorNameLF": "Author, Ann",
              "narrators": [
                "Nia Narrator"
              ],
              "narratorName": "Nia Narrator",
              "series": [],
              "seriesName": "The Saga #1",
              "genres": [
                "Fantasy"
              ],
              "explicit": false,
              "abridged": false
            },
            "tags": [],
            "numTracks": 1,
            "numAudioFiles": 1,
            "numChapters": 0,
            "duration": 36000.0,
            "size": 100000
          },
          "numFiles": 1,
          "size": 100000
        }
      ],
      "series": [
        {
          "id": "li_8f14e45fceea467f",
          "name": "Ann Author",
          "items": []
        }
      ]
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/libraries/{id}/search`.",
  "required": [
    "book",
    "podcast",
    "narrators",
    "tags",
    "genres",
    "series",
    "authors"
  ],
  "properties": {
    "book": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An item that matched a search.",
        "required": [
          "libraryItem"
        ],
        "properties": {
          "libraryItem": {
            "type": "object",
            "description": "The item.",
            "required": [
              "id",
              "ino",
              "libraryId",
              "folderId",
              "path",
              "relPath",
              "isFile",
              "mtimeMs",
              "ctimeMs",
              "birthtimeMs",
              "addedAt",
              "updatedAt",
              "isMissing",
              "isInvalid",
              "mediaType",
              "media",
              "numFiles",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The item id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "ino": {
                "type": "string",
                "description": "The item's inode as apps expect one: the edition id again.",
                "example": "0"
              },
              "oldLibraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "libraryId": {
                "type": "string",
                "description": "The library the item is listed in.",
                "example": "bookclerk-library"
              },
              "folderId": {
                "type": "string",
                "description": "The folder id: the library id.",
                "example": "bookclerk-library"
              },
              "path": {
                "type": "string",
                "description": "A display path: the title.",
                "example": "/the-first.m4b"
              },
              "relPath": {
                "type": "string",
                "description": "A display path: the title.",
                "example": "the-first.m4b"
              },
              "isFile": {
                "type": "boolean",
                "description": "Always false: an item is a folder of tracks.",
                "example": true
              },
              "mtimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the copy last changed, in epoch milliseconds.",
                "example": 1763600000000
              },
              "ctimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the copy was stored, in epoch milliseconds.",
                "example": 1763600000000
              },
              "birthtimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the copy was stored, in epoch milliseconds.",
                "example": 1763600000000
              },
              "addedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the item joined the library, in epoch milliseconds.",
                "example": 1763600000000
              },
              "updatedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When its record last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "isMissing": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "isInvalid": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "mediaType": {
                "type": "string",
                "description": "Always [`MEDIA_TYPE_BOOK`].",
                "example": "book"
              },
              "media": {
                "type": "object",
                "description": "The book.",
                "required": [
                  "id",
                  "metadata",
                  "tags",
                  "numTracks",
                  "numAudioFiles",
                  "numChapters",
                  "duration",
                  "size"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The media id: the edition id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "libraryItemId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The item id, when fetched expanded.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "The book's metadata.",
                    "required": [
                      "title",
                      "titleIgnorePrefix",
                      "authors",
                      "authorName",
                      "authorNameLF",
                      "narrators",
                      "narratorName",
                      "series",
                      "seriesName",
                      "genres",
                      "explicit",
                      "abridged"
                    ],
                    "properties": {
                      "title": {
                        "type": "string",
                        "description": "The title.",
                        "example": "The First"
                      },
                      "titleIgnorePrefix": {
                        "type": "string",
                        "description": "The title for sorting.",
                        "example": "First, The"
                      },
                      "subtitle": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The subtitle, if any.",
                        "example": "A Novel"
                      },
                      "authors": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "description": "An id and a name.",
                          "required": [
                            "id",
                            "name"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "The entity's id.",
                              "example": "li_8f14e45fceea467f"
                            },
                            "name": {
                              "type": "string",
                              "description": "Its display name.",
                              "example": "Ann Author"
                            }
                          }
                        },
                        "description": "The authors."
                      },
                      "authorName": {
                        "type": "string",
                        "description": "The authors' names joined with `, `.",
                        "example": "Ann Author"
                      },
                      "authorNameLF": {
                        "type": "string",
                        "description": "The authors' names, family name first, joined with `, `.",
                        "example": "Author, Ann"
                      },
                      "narrators": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "The narrators' names.",
                        "example": [
                          "Nia Narrator"
                        ]
                      },
                      "narratorName": {
                        "type": "string",
                        "description": "The narrators' names joined with `, `.",
                        "example": "Nia Narrator"
                      },
                      "series": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "description": "A series an item belongs to, with the item's place in it.",
                          "required": [
                            "id",
                            "name"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "The series id.",
                              "example": "li_8f14e45fceea467f"
                            },
                            "name": {
                              "type": "string",
                              "description": "The series name.",
                              "example": "Ann Author"
                            },
                            "sequence": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                              "example": "1"
                            }
                          }
                        },
                        "description": "The series the book is in."
                      },
                      "seriesName": {
                        "type": "string",
                        "description": "The series names with the book's place (`Name #2`), joined.",
                        "example": "The Saga #1"
                      },
                      "genres": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Genres.",
                        "example": [
                          "Fantasy"
                        ]
                      },
                      "publishedYear": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The year of publication, as a string (`\"2019\"`).",
                        "example": "2024"
                      },
                      "publishedDate": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The date of publication, if known.",
                        "example": "2024-03-01"
                      },
                      "publisher": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The publisher.",
                        "example": "Example Press"
                      },
                      "description": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The description, as the library stores it.",
                        "example": "A short description."
                      },
                      "descriptionPlain": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The description with markup removed.",
                        "example": "A short description."
                      },
                      "isbn": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The ISBN, if known.",
                        "example": "9780000000002"
                      },
                      "asin": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The ASIN, if known.",
                        "example": "B000000000"
                      },
                      "language": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The language.",
                        "example": "en-us"
                      },
                      "explicit": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "abridged": {
                        "type": "boolean",
                        "description": "Whether the edition is abridged.",
                        "example": false
                      }
                    }
                  },
                  "coverPath": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                    "example": "/player/api/items/li_8f14e45fceea467f/cover"
                  },
                  "tags": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Tags: none.",
                    "example": []
                  },
                  "numTracks": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Tracks in play order.",
                    "example": 1,
                    "minimum": 0
                  },
                  "numAudioFiles": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Audio files.",
                    "example": 1,
                    "minimum": 0
                  },
                  "numChapters": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Chapters.",
                    "example": 0,
                    "minimum": 0
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds.",
                    "example": 36000.0
                  },
                  "size": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Bytes in its audio files.",
                    "example": 100000,
                    "minimum": 0
                  },
                  "audioFiles": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "description": "An audio file of a book.",
                      "required": [
                        "index",
                        "ino",
                        "metadata",
                        "addedAt",
                        "updatedAt",
                        "manuallyVerified",
                        "exclude",
                        "duration",
                        "chapters",
                        "metaTags",
                        "mimeType"
                      ],
                      "properties": {
                        "index": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's place in play order, from 1.",
                          "example": 1,
                          "minimum": 0
                        },
                        "ino": {
                          "type": "string",
                          "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                          "example": "0"
                        },
                        "metadata": {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        "addedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "updatedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "trackNumFromMeta": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "The track number the file's tags state: not read.",
                          "example": 1,
                          "minimum": 0
                        },
                        "discNumFromMeta": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "The disc number the file's tags state: not read.",
                          "example": null,
                          "minimum": 0
                        },
                        "trackNumFromFilename": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "The track number in the file name: not read.",
                          "example": null,
                          "minimum": 0
                        },
                        "discNumFromFilename": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "The disc number in the file name: not read.",
                          "example": null,
                          "minimum": 0
                        },
                        "manuallyVerified": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "exclude": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "error": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "format": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The container format, such as `mp4` or `mp3`.",
                          "example": "MP4A"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The file's length in seconds.",
                          "example": 36000.0
                        },
                        "bitRate": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "Bits per second, if known.",
                          "example": 128000,
                          "minimum": 0
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The file's language, if known.",
                          "example": "en-us"
                        },
                        "codec": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The codec, if known.",
                          "example": "aac"
                        },
                        "timeBase": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The time base, if known.",
                          "example": "1/44100"
                        },
                        "channels": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "Audio channels, if known.",
                          "example": 2,
                          "minimum": 0
                        },
                        "channelLayout": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The channel layout, if known.",
                          "example": "stereo"
                        },
                        "chapters": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A chapter of a book.",
                            "required": [
                              "id",
                              "start",
                              "end",
                              "title"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The chapter's place, from 0.",
                                "example": 1,
                                "minimum": 0
                              },
                              "start": {
                                "type": "number",
                                "format": "double",
                                "description": "Where it starts, in seconds.",
                                "example": 0.0
                              },
                              "end": {
                                "type": "number",
                                "format": "double",
                                "description": "Where it ends, in seconds.",
                                "example": 600.0
                              },
                              "title": {
                                "type": "string",
                                "description": "Its title.",
                                "example": "The First"
                              }
                            }
                          },
                          "description": "Chapters embedded in the file: none are read."
                        },
                        "embeddedCoverArt": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "metaTags": {
                          "type": "object",
                          "description": "Tags read from the file: none until the stored media probe reads\nthem."
                        },
                        "mimeType": {
                          "type": "string",
                          "description": "The file's media type, such as `audio/mp4`.",
                          "example": "audio/mp4"
                        }
                      }
                    },
                    "description": "The audio files, when fetched expanded."
                  },
                  "chapters": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "description": "A chapter of a book.",
                      "required": [
                        "id",
                        "start",
                        "end",
                        "title"
                      ],
                      "properties": {
                        "id": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The chapter's place, from 0.",
                          "example": 1,
                          "minimum": 0
                        },
                        "start": {
                          "type": "number",
                          "format": "double",
                          "description": "Where it starts, in seconds.",
                          "example": 0.0
                        },
                        "end": {
                          "type": "number",
                          "format": "double",
                          "description": "Where it ends, in seconds.",
                          "example": 600.0
                        },
                        "title": {
                          "type": "string",
                          "description": "Its title.",
                          "example": "The First"
                        }
                      }
                    },
                    "description": "The chapters, when fetched expanded."
                  },
                  "tracks": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "description": "A track with its place in the book.",
                      "required": [
                        "index",
                        "startOffset",
                        "duration",
                        "title",
                        "contentUrl",
                        "mimeType"
                      ],
                      "properties": {
                        "index": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The track's place in play order, from 1.",
                          "example": 1,
                          "minimum": 0
                        },
                        "startOffset": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the track starts in the book, in seconds.",
                          "example": 0.0
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The track's length in seconds.",
                          "example": 36000.0
                        },
                        "title": {
                          "type": "string",
                          "description": "The track's title: its file name.",
                          "example": "The First"
                        },
                        "contentUrl": {
                          "type": "string",
                          "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                          "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                        },
                        "mimeType": {
                          "type": "string",
                          "description": "The track's media type.",
                          "example": "audio/mp4"
                        },
                        "codec": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The codec, if known.",
                          "example": "aac"
                        },
                        "metadata": {
                          "oneOf": [
                            {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            {
                              "type": "null"
                            }
                          ]
                        }
                      }
                    },
                    "description": "The tracks with their place in the book, when fetched expanded."
                  }
                }
              },
              "numFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Files in the item.",
                "example": 1,
                "minimum": 0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in all its files.",
                "example": 100000,
                "minimum": 0
              },
              "libraryFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A file of an item, in the expanded item's `libraryFiles`.",
                  "required": [
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "fileType"
                  ],
                  "properties": {
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "fileType": {
                      "type": "string",
                      "description": "Always `audio`.",
                      "example": "audio"
                    }
                  }
                },
                "description": "The item's files, when the item is fetched expanded."
              },
              "userMediaProgress": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "The patron's progress, when the app asked for it.",
                    "required": [
                      "id",
                      "userId",
                      "libraryItemId",
                      "mediaItemId",
                      "mediaItemType",
                      "duration",
                      "progress",
                      "currentTime",
                      "isFinished",
                      "hideFromContinueListening",
                      "lastUpdate",
                      "startedAt"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The progress id: the item id (one record per patron and item).",
                        "example": "li_8f14e45fceea467f"
                      },
                      "userId": {
                        "type": "string",
                        "description": "The patron's id.",
                        "example": "42"
                      },
                      "libraryItemId": {
                        "type": "string",
                        "description": "The item id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "episodeId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "mediaItemId": {
                        "type": "string",
                        "description": "The media id: the item id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "mediaItemType": {
                        "type": "string",
                        "description": "Always `book`.",
                        "example": "book"
                      },
                      "duration": {
                        "type": "number",
                        "format": "double",
                        "description": "The book's length in seconds, as last reported.",
                        "example": 36000.0
                      },
                      "progress": {
                        "type": "number",
                        "format": "double",
                        "description": "The share listened, from 0 to 1.",
                        "example": 0.05
                      },
                      "currentTime": {
                        "type": "number",
                        "format": "double",
                        "description": "Where the patron is, in seconds.",
                        "example": 1830.5
                      },
                      "isFinished": {
                        "type": "boolean",
                        "description": "Whether the patron finished it.",
                        "example": false
                      },
                      "hideFromContinueListening": {
                        "type": "boolean",
                        "description": "Whether it is hidden from continue listening.",
                        "example": false
                      },
                      "ebookLocation": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "ebookProgress": {
                        "type": [
                          "number",
                          "null"
                        ],
                        "format": "double",
                        "description": "Always null.",
                        "example": null
                      },
                      "lastUpdate": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the progress last changed, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "startedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the patron started, in epoch milliseconds.",
                        "example": 1763620000000
                      },
                      "finishedAt": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "When the patron finished, in epoch milliseconds.",
                        "example": null
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              },
              "seriesSequence": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item's place in a series, on a series' book list.",
                "example": "1"
              }
            }
          }
        }
      },
      "description": "Matching items."
    },
    "podcast": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Always empty.",
      "example": []
    },
    "narrators": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A narrator with how many items they read.",
        "required": [
          "id",
          "name",
          "numBooks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The name in URL-safe base64, as apps filter by it.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "The narrator's name.",
            "example": "Ann Author"
          },
          "numBooks": {
            "type": "integer",
            "format": "int64",
            "description": "Items they read that the patron can see.",
            "example": 1,
            "minimum": 0
          }
        }
      },
      "description": "Matching narrators."
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Always empty.",
      "example": []
    },
    "genres": {
      "type": "array",
      "items": {
        "type": "object"
      },
      "description": "Always empty.",
      "example": []
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A series that matched a search.",
        "required": [
          "series",
          "books"
        ],
        "properties": {
          "series": {
            "type": "object",
            "description": "The series.",
            "required": [
              "id",
              "name",
              "nameIgnorePrefix",
              "addedAt",
              "updatedAt",
              "libraryId"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The series id.",
                "example": "li_8f14e45fceea467f"
              },
              "name": {
                "type": "string",
                "description": "Its name.",
                "example": "Ann Author"
              },
              "nameIgnorePrefix": {
                "type": "string",
                "description": "The name for sorting.",
                "example": "Saga, The"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Its description: none.",
                "example": "A short description."
              },
              "addedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the library first saw it, in epoch milliseconds.",
                "example": 1763600000000
              },
              "updatedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When it last changed, in epoch milliseconds.",
                "example": 1763630000000
              },
              "libraryId": {
                "type": "string",
                "description": "The library it is listed in.",
                "example": "bookclerk-library"
              },
              "books": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An item: an edition with a stored copy.",
                  "required": [
                    "id",
                    "ino",
                    "libraryId",
                    "folderId",
                    "path",
                    "relPath",
                    "isFile",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs",
                    "addedAt",
                    "updatedAt",
                    "isMissing",
                    "isInvalid",
                    "mediaType",
                    "media",
                    "numFiles",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The item id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "ino": {
                      "type": "string",
                      "description": "The item's inode as apps expect one: the edition id again.",
                      "example": "0"
                    },
                    "oldLibraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "libraryId": {
                      "type": "string",
                      "description": "The library the item is listed in.",
                      "example": "bookclerk-library"
                    },
                    "folderId": {
                      "type": "string",
                      "description": "The folder id: the library id.",
                      "example": "bookclerk-library"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the title.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the title.",
                      "example": "the-first.m4b"
                    },
                    "isFile": {
                      "type": "boolean",
                      "description": "Always false: an item is a folder of tracks.",
                      "example": true
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the copy last changed, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the copy was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the copy was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the item joined the library, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When its record last changed, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "isMissing": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "isInvalid": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "mediaType": {
                      "type": "string",
                      "description": "Always [`MEDIA_TYPE_BOOK`].",
                      "example": "book"
                    },
                    "media": {
                      "type": "object",
                      "description": "The book.",
                      "required": [
                        "id",
                        "metadata",
                        "tags",
                        "numTracks",
                        "numAudioFiles",
                        "numChapters",
                        "duration",
                        "size"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The media id: the edition id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "libraryItemId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item id, when fetched expanded.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "metadata": {
                          "type": "object",
                          "description": "The book's metadata.",
                          "required": [
                            "title",
                            "titleIgnorePrefix",
                            "authors",
                            "authorName",
                            "authorNameLF",
                            "narrators",
                            "narratorName",
                            "series",
                            "seriesName",
                            "genres",
                            "explicit",
                            "abridged"
                          ],
                          "properties": {
                            "title": {
                              "type": "string",
                              "description": "The title.",
                              "example": "The First"
                            },
                            "titleIgnorePrefix": {
                              "type": "string",
                              "description": "The title for sorting.",
                              "example": "First, The"
                            },
                            "subtitle": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The subtitle, if any.",
                              "example": "A Novel"
                            },
                            "authors": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "description": "An id and a name.",
                                "required": [
                                  "id",
                                  "name"
                                ],
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "The entity's id.",
                                    "example": "li_8f14e45fceea467f"
                                  },
                                  "name": {
                                    "type": "string",
                                    "description": "Its display name.",
                                    "example": "Ann Author"
                                  }
                                }
                              },
                              "description": "The authors."
                            },
                            "authorName": {
                              "type": "string",
                              "description": "The authors' names joined with `, `.",
                              "example": "Ann Author"
                            },
                            "authorNameLF": {
                              "type": "string",
                              "description": "The authors' names, family name first, joined with `, `.",
                              "example": "Author, Ann"
                            },
                            "narrators": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "The narrators' names.",
                              "example": [
                                "Nia Narrator"
                              ]
                            },
                            "narratorName": {
                              "type": "string",
                              "description": "The narrators' names joined with `, `.",
                              "example": "Nia Narrator"
                            },
                            "series": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "description": "A series an item belongs to, with the item's place in it.",
                                "required": [
                                  "id",
                                  "name"
                                ],
                                "properties": {
                                  "id": {
                                    "type": "string",
                                    "description": "The series id.",
                                    "example": "li_8f14e45fceea467f"
                                  },
                                  "name": {
                                    "type": "string",
                                    "description": "The series name.",
                                    "example": "Ann Author"
                                  },
                                  "sequence": {
                                    "type": [
                                      "string",
                                      "null"
                                    ],
                                    "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                    "example": "1"
                                  }
                                }
                              },
                              "description": "The series the book is in."
                            },
                            "seriesName": {
                              "type": "string",
                              "description": "The series names with the book's place (`Name #2`), joined.",
                              "example": "The Saga #1"
                            },
                            "genres": {
                              "type": "array",
                              "items": {
                                "type": "string"
                              },
                              "description": "Genres.",
                              "example": [
                                "Fantasy"
                              ]
                            },
                            "publishedYear": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The year of publication, as a string (`\"2019\"`).",
                              "example": "2024"
                            },
                            "publishedDate": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The date of publication, if known.",
                              "example": "2024-03-01"
                            },
                            "publisher": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The publisher.",
                              "example": "Example Press"
                            },
                            "description": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The description, as the library stores it.",
                              "example": "A short description."
                            },
                            "descriptionPlain": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The description with markup removed.",
                              "example": "A short description."
                            },
                            "isbn": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The ISBN, if known.",
                              "example": "9780000000002"
                            },
                            "asin": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The ASIN, if known.",
                              "example": "B000000000"
                            },
                            "language": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The language.",
                              "example": "en-us"
                            },
                            "explicit": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "abridged": {
                              "type": "boolean",
                              "description": "Whether the edition is abridged.",
                              "example": false
                            }
                          }
                        },
                        "coverPath": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                          "example": "/player/api/items/li_8f14e45fceea467f/cover"
                        },
                        "tags": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Tags: none.",
                          "example": []
                        },
                        "numTracks": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Tracks in play order.",
                          "example": 1,
                          "minimum": 0
                        },
                        "numAudioFiles": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Audio files.",
                          "example": 1,
                          "minimum": 0
                        },
                        "numChapters": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Chapters.",
                          "example": 0,
                          "minimum": 0
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds.",
                          "example": 36000.0
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "Bytes in its audio files.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "audioFiles": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "description": "An audio file of a book.",
                            "required": [
                              "index",
                              "ino",
                              "metadata",
                              "addedAt",
                              "updatedAt",
                              "manuallyVerified",
                              "exclude",
                              "duration",
                              "chapters",
                              "metaTags",
                              "mimeType"
                            ],
                            "properties": {
                              "index": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's place in play order, from 1.",
                                "example": 1,
                                "minimum": 0
                              },
                              "ino": {
                                "type": "string",
                                "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                "example": "0"
                              },
                              "metadata": {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              "addedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "updatedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763630000000
                              },
                              "trackNumFromMeta": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "The track number the file's tags state: not read.",
                                "example": 1,
                                "minimum": 0
                              },
                              "discNumFromMeta": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "The disc number the file's tags state: not read.",
                                "example": null,
                                "minimum": 0
                              },
                              "trackNumFromFilename": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "The track number in the file name: not read.",
                                "example": null,
                                "minimum": 0
                              },
                              "discNumFromFilename": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "The disc number in the file name: not read.",
                                "example": null,
                                "minimum": 0
                              },
                              "manuallyVerified": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "exclude": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "error": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "format": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The container format, such as `mp4` or `mp3`.",
                                "example": "MP4A"
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The file's length in seconds.",
                                "example": 36000.0
                              },
                              "bitRate": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "Bits per second, if known.",
                                "example": 128000,
                                "minimum": 0
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The file's language, if known.",
                                "example": "en-us"
                              },
                              "codec": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The codec, if known.",
                                "example": "aac"
                              },
                              "timeBase": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The time base, if known.",
                                "example": "1/44100"
                              },
                              "channels": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "Audio channels, if known.",
                                "example": 2,
                                "minimum": 0
                              },
                              "channelLayout": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The channel layout, if known.",
                                "example": "stereo"
                              },
                              "chapters": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "A chapter of a book.",
                                  "required": [
                                    "id",
                                    "start",
                                    "end",
                                    "title"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The chapter's place, from 0.",
                                      "example": 1,
                                      "minimum": 0
                                    },
                                    "start": {
                                      "type": "number",
                                      "format": "double",
                                      "description": "Where it starts, in seconds.",
                                      "example": 0.0
                                    },
                                    "end": {
                                      "type": "number",
                                      "format": "double",
                                      "description": "Where it ends, in seconds.",
                                      "example": 600.0
                                    },
                                    "title": {
                                      "type": "string",
                                      "description": "Its title.",
                                      "example": "The First"
                                    }
                                  }
                                },
                                "description": "Chapters embedded in the file: none are read."
                              },
                              "embeddedCoverArt": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "metaTags": {
                                "type": "object",
                                "description": "Tags read from the file: none until the stored media probe reads\nthem."
                              },
                              "mimeType": {
                                "type": "string",
                                "description": "The file's media type, such as `audio/mp4`.",
                                "example": "audio/mp4"
                              }
                            }
                          },
                          "description": "The audio files, when fetched expanded."
                        },
                        "chapters": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "description": "A chapter of a book.",
                            "required": [
                              "id",
                              "start",
                              "end",
                              "title"
                            ],
                            "properties": {
                              "id": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The chapter's place, from 0.",
                                "example": 1,
                                "minimum": 0
                              },
                              "start": {
                                "type": "number",
                                "format": "double",
                                "description": "Where it starts, in seconds.",
                                "example": 0.0
                              },
                              "end": {
                                "type": "number",
                                "format": "double",
                                "description": "Where it ends, in seconds.",
                                "example": 600.0
                              },
                              "title": {
                                "type": "string",
                                "description": "Its title.",
                                "example": "The First"
                              }
                            }
                          },
                          "description": "The chapters, when fetched expanded."
                        },
                        "tracks": {
                          "type": [
                            "array",
                            "null"
                          ],
                          "items": {
                            "type": "object",
                            "description": "A track with its place in the book.",
                            "required": [
                              "index",
                              "startOffset",
                              "duration",
                              "title",
                              "contentUrl",
                              "mimeType"
                            ],
                            "properties": {
                              "index": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The track's place in play order, from 1.",
                                "example": 1,
                                "minimum": 0
                              },
                              "startOffset": {
                                "type": "number",
                                "format": "double",
                                "description": "Where the track starts in the book, in seconds.",
                                "example": 0.0
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The track's length in seconds.",
                                "example": 36000.0
                              },
                              "title": {
                                "type": "string",
                                "description": "The track's title: its file name.",
                                "example": "The First"
                              },
                              "contentUrl": {
                                "type": "string",
                                "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                              },
                              "mimeType": {
                                "type": "string",
                                "description": "The track's media type.",
                                "example": "audio/mp4"
                              },
                              "codec": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The codec, if known.",
                                "example": "aac"
                              },
                              "metadata": {
                                "oneOf": [
                                  {
                                    "type": "object",
                                    "description": "The file's name, size and times.",
                                    "required": [
                                      "filename",
                                      "ext",
                                      "path",
                                      "relPath",
                                      "size",
                                      "mtimeMs",
                                      "ctimeMs",
                                      "birthtimeMs"
                                    ],
                                    "properties": {
                                      "filename": {
                                        "type": "string",
                                        "description": "The file name.",
                                        "example": "the-first.m4b"
                                      },
                                      "ext": {
                                        "type": "string",
                                        "description": "The extension with its dot (`.m4b`).",
                                        "example": ".m4b"
                                      },
                                      "path": {
                                        "type": "string",
                                        "description": "A display path: the file name.",
                                        "example": "/the-first.m4b"
                                      },
                                      "relPath": {
                                        "type": "string",
                                        "description": "A display path: the file name.",
                                        "example": "the-first.m4b"
                                      },
                                      "size": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The file's size in bytes.",
                                        "example": 100000,
                                        "minimum": 0
                                      },
                                      "mtimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      },
                                      "ctimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      },
                                      "birthtimeMs": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "When the file was stored, in epoch milliseconds.",
                                        "example": 1763600000000
                                      }
                                    }
                                  },
                                  {
                                    "type": "null"
                                  }
                                ]
                              }
                            }
                          },
                          "description": "The tracks with their place in the book, when fetched expanded."
                        }
                      }
                    },
                    "numFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Files in the item.",
                      "example": 1,
                      "minimum": 0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in all its files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "libraryFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A file of an item, in the expanded item's `libraryFiles`.",
                        "required": [
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "fileType"
                        ],
                        "properties": {
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "fileType": {
                            "type": "string",
                            "description": "Always `audio`.",
                            "example": "audio"
                          }
                        }
                      },
                      "description": "The item's files, when the item is fetched expanded."
                    },
                    "userMediaProgress": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The patron's progress, when the app asked for it.",
                          "required": [
                            "id",
                            "userId",
                            "libraryItemId",
                            "mediaItemId",
                            "mediaItemType",
                            "duration",
                            "progress",
                            "currentTime",
                            "isFinished",
                            "hideFromContinueListening",
                            "lastUpdate",
                            "startedAt"
                          ],
                          "properties": {
                            "id": {
                              "type": "string",
                              "description": "The progress id: the item id (one record per patron and item).",
                              "example": "li_8f14e45fceea467f"
                            },
                            "userId": {
                              "type": "string",
                              "description": "The patron's id.",
                              "example": "42"
                            },
                            "libraryItemId": {
                              "type": "string",
                              "description": "The item id.",
                              "example": "li_8f14e45fceea467f"
                            },
                            "episodeId": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "mediaItemId": {
                              "type": "string",
                              "description": "The media id: the item id.",
                              "example": "li_8f14e45fceea467f"
                            },
                            "mediaItemType": {
                              "type": "string",
                              "description": "Always `book`.",
                              "example": "book"
                            },
                            "duration": {
                              "type": "number",
                              "format": "double",
                              "description": "The book's length in seconds, as last reported.",
                              "example": 36000.0
                            },
                            "progress": {
                              "type": "number",
                              "format": "double",
                              "description": "The share listened, from 0 to 1.",
                              "example": 0.05
                            },
                            "currentTime": {
                              "type": "number",
                              "format": "double",
                              "description": "Where the patron is, in seconds.",
                              "example": 1830.5
                            },
                            "isFinished": {
                              "type": "boolean",
                              "description": "Whether the patron finished it.",
                              "example": false
                            },
                            "hideFromContinueListening": {
                              "type": "boolean",
                              "description": "Whether it is hidden from continue listening.",
                              "example": false
                            },
                            "ebookLocation": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "ebookProgress": {
                              "type": [
                                "number",
                                "null"
                              ],
                              "format": "double",
                              "description": "Always null.",
                              "example": null
                            },
                            "lastUpdate": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the progress last changed, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "startedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the patron started, in epoch milliseconds.",
                              "example": 1763620000000
                            },
                            "finishedAt": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "When the patron finished, in epoch milliseconds.",
                              "example": null
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    },
                    "seriesSequence": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item's place in a series, on a series' book list.",
                      "example": "1"
                    }
                  }
                },
                "description": "Its items in series order, on lists."
              },
              "progress": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "The patron's progress through it, when asked for.",
                    "required": [
                      "libraryItemIds",
                      "libraryItemIdsFinished",
                      "isFinished"
                    ],
                    "properties": {
                      "libraryItemIds": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "The series' items, by id.",
                        "example": [
                          "li_8f14e45fceea467f"
                        ]
                      },
                      "libraryItemIdsFinished": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Those the patron finished.",
                        "example": []
                      },
                      "isFinished": {
                        "type": "boolean",
                        "description": "Whether the patron finished every one.",
                        "example": false
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "books": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "Its items."
          }
        }
      },
      "description": "Matching series."
    },
    "authors": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An author.",
        "required": [
          "id",
          "name",
          "lastFirst",
          "libraryId",
          "addedAt",
          "updatedAt",
          "numBooks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The contributor id.",
            "example": "li_8f14e45fceea467f"
          },
          "asin": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": "B000000000"
          },
          "name": {
            "type": "string",
            "description": "The author's name.",
            "example": "Ann Author"
          },
          "lastFirst": {
            "type": "string",
            "description": "The name family name first.",
            "example": "Author, Ann"
          },
          "description": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": "A short description."
          },
          "imagePath": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null: no author images.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library it is listed in.",
            "example": "bookclerk-library"
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the library first saw the author, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "numBooks": {
            "type": "integer",
            "format": "int64",
            "description": "Items by the author the patron can see.",
            "example": 1,
            "minimum": 0
          },
          "libraryItems": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "The author's items, when asked for."
          },
          "series": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A series of an author's, with the author's items in it.",
              "required": [
                "id",
                "name",
                "items"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The series id.",
                  "example": "li_8f14e45fceea467f"
                },
                "name": {
                  "type": "string",
                  "description": "The series name.",
                  "example": "Ann Author"
                },
                "items": {
                  "type": "array",
                  "items": {
                    "type": "object",
                    "description": "An item: an edition with a stored copy.",
                    "required": [
                      "id",
                      "ino",
                      "libraryId",
                      "folderId",
                      "path",
                      "relPath",
                      "isFile",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs",
                      "addedAt",
                      "updatedAt",
                      "isMissing",
                      "isInvalid",
                      "mediaType",
                      "media",
                      "numFiles",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The item id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "ino": {
                        "type": "string",
                        "description": "The item's inode as apps expect one: the edition id again.",
                        "example": "0"
                      },
                      "oldLibraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "libraryId": {
                        "type": "string",
                        "description": "The library the item is listed in.",
                        "example": "bookclerk-library"
                      },
                      "folderId": {
                        "type": "string",
                        "description": "The folder id: the library id.",
                        "example": "bookclerk-library"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the title.",
                        "example": "the-first.m4b"
                      },
                      "isFile": {
                        "type": "boolean",
                        "description": "Always false: an item is a folder of tracks.",
                        "example": true
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy last changed, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the copy was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the item joined the library, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When its record last changed, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "isMissing": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "isInvalid": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "mediaType": {
                        "type": "string",
                        "description": "Always [`MEDIA_TYPE_BOOK`].",
                        "example": "book"
                      },
                      "media": {
                        "type": "object",
                        "description": "The book.",
                        "required": [
                          "id",
                          "metadata",
                          "tags",
                          "numTracks",
                          "numAudioFiles",
                          "numChapters",
                          "duration",
                          "size"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The media id: the edition id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "libraryItemId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The item id, when fetched expanded.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The book's metadata.",
                            "required": [
                              "title",
                              "titleIgnorePrefix",
                              "authors",
                              "authorName",
                              "authorNameLF",
                              "narrators",
                              "narratorName",
                              "series",
                              "seriesName",
                              "genres",
                              "explicit",
                              "abridged"
                            ],
                            "properties": {
                              "title": {
                                "type": "string",
                                "description": "The title.",
                                "example": "The First"
                              },
                              "titleIgnorePrefix": {
                                "type": "string",
                                "description": "The title for sorting.",
                                "example": "First, The"
                              },
                              "subtitle": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The subtitle, if any.",
                                "example": "A Novel"
                              },
                              "authors": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "An id and a name.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The entity's id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "Its display name.",
                                      "example": "Ann Author"
                                    }
                                  }
                                },
                                "description": "The authors."
                              },
                              "authorName": {
                                "type": "string",
                                "description": "The authors' names joined with `, `.",
                                "example": "Ann Author"
                              },
                              "authorNameLF": {
                                "type": "string",
                                "description": "The authors' names, family name first, joined with `, `.",
                                "example": "Author, Ann"
                              },
                              "narrators": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "The narrators' names.",
                                "example": [
                                  "Nia Narrator"
                                ]
                              },
                              "narratorName": {
                                "type": "string",
                                "description": "The narrators' names joined with `, `.",
                                "example": "Nia Narrator"
                              },
                              "series": {
                                "type": "array",
                                "items": {
                                  "type": "object",
                                  "description": "A series an item belongs to, with the item's place in it.",
                                  "required": [
                                    "id",
                                    "name"
                                  ],
                                  "properties": {
                                    "id": {
                                      "type": "string",
                                      "description": "The series id.",
                                      "example": "li_8f14e45fceea467f"
                                    },
                                    "name": {
                                      "type": "string",
                                      "description": "The series name.",
                                      "example": "Ann Author"
                                    },
                                    "sequence": {
                                      "type": [
                                        "string",
                                        "null"
                                      ],
                                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                      "example": "1"
                                    }
                                  }
                                },
                                "description": "The series the book is in."
                              },
                              "seriesName": {
                                "type": "string",
                                "description": "The series names with the book's place (`Name #2`), joined.",
                                "example": "The Saga #1"
                              },
                              "genres": {
                                "type": "array",
                                "items": {
                                  "type": "string"
                                },
                                "description": "Genres.",
                                "example": [
                                  "Fantasy"
                                ]
                              },
                              "publishedYear": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The year of publication, as a string (`\"2019\"`).",
                                "example": "2024"
                              },
                              "publishedDate": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The date of publication, if known.",
                                "example": "2024-03-01"
                              },
                              "publisher": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The publisher.",
                                "example": "Example Press"
                              },
                              "description": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description, as the library stores it.",
                                "example": "A short description."
                              },
                              "descriptionPlain": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The description with markup removed.",
                                "example": "A short description."
                              },
                              "isbn": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ISBN, if known.",
                                "example": "9780000000002"
                              },
                              "asin": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The ASIN, if known.",
                                "example": "B000000000"
                              },
                              "language": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The language.",
                                "example": "en-us"
                              },
                              "explicit": {
                                "type": "boolean",
                                "description": "Always false.",
                                "example": false
                              },
                              "abridged": {
                                "type": "boolean",
                                "description": "Whether the edition is abridged.",
                                "example": false
                              }
                            }
                          },
                          "coverPath": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/cover"
                          },
                          "tags": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Tags: none.",
                            "example": []
                          },
                          "numTracks": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Tracks in play order.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numAudioFiles": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Audio files.",
                            "example": 1,
                            "minimum": 0
                          },
                          "numChapters": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Chapters.",
                            "example": 0,
                            "minimum": 0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds.",
                            "example": 36000.0
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "Bytes in its audio files.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "audioFiles": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "An audio file of a book.",
                              "required": [
                                "index",
                                "ino",
                                "metadata",
                                "addedAt",
                                "updatedAt",
                                "manuallyVerified",
                                "exclude",
                                "duration",
                                "chapters",
                                "metaTags",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "ino": {
                                  "type": "string",
                                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                                  "example": "0"
                                },
                                "metadata": {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                "addedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "updatedAt": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763630000000
                                },
                                "trackNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number the file's tags state: not read.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "discNumFromMeta": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number the file's tags state: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "trackNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The track number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "discNumFromFilename": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "The disc number in the file name: not read.",
                                  "example": null,
                                  "minimum": 0
                                },
                                "manuallyVerified": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "exclude": {
                                  "type": "boolean",
                                  "description": "Always false.",
                                  "example": false
                                },
                                "error": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "format": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The container format, such as `mp4` or `mp3`.",
                                  "example": "MP4A"
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The file's length in seconds.",
                                  "example": 36000.0
                                },
                                "bitRate": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Bits per second, if known.",
                                  "example": 128000,
                                  "minimum": 0
                                },
                                "language": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The file's language, if known.",
                                  "example": "en-us"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "timeBase": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The time base, if known.",
                                  "example": "1/44100"
                                },
                                "channels": {
                                  "type": [
                                    "integer",
                                    "null"
                                  ],
                                  "format": "int64",
                                  "description": "Audio channels, if known.",
                                  "example": 2,
                                  "minimum": 0
                                },
                                "channelLayout": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The channel layout, if known.",
                                  "example": "stereo"
                                },
                                "chapters": {
                                  "type": "array",
                                  "items": {
                                    "type": "object",
                                    "description": "A chapter of a book.",
                                    "required": [
                                      "id",
                                      "start",
                                      "end",
                                      "title"
                                    ],
                                    "properties": {
                                      "id": {
                                        "type": "integer",
                                        "format": "int64",
                                        "description": "The chapter's place, from 0.",
                                        "example": 1,
                                        "minimum": 0
                                      },
                                      "start": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it starts, in seconds.",
                                        "example": 0.0
                                      },
                                      "end": {
                                        "type": "number",
                                        "format": "double",
                                        "description": "Where it ends, in seconds.",
                                        "example": 600.0
                                      },
                                      "title": {
                                        "type": "string",
                                        "description": "Its title.",
                                        "example": "The First"
                                      }
                                    }
                                  },
                                  "description": "Chapters embedded in the file: none are read."
                                },
                                "embeddedCoverArt": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "Always null.",
                                  "example": null
                                },
                                "metaTags": {
                                  "type": "object",
                                  "description": "Tags read from the file: none until the stored media probe reads\nthem."
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The file's media type, such as `audio/mp4`.",
                                  "example": "audio/mp4"
                                }
                              }
                            },
                            "description": "The audio files, when fetched expanded."
                          },
                          "chapters": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "The chapters, when fetched expanded."
                          },
                          "tracks": {
                            "type": [
                              "array",
                              "null"
                            ],
                            "items": {
                              "type": "object",
                              "description": "A track with its place in the book.",
                              "required": [
                                "index",
                                "startOffset",
                                "duration",
                                "title",
                                "contentUrl",
                                "mimeType"
                              ],
                              "properties": {
                                "index": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The track's place in play order, from 1.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "startOffset": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where the track starts in the book, in seconds.",
                                  "example": 0.0
                                },
                                "duration": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "The track's length in seconds.",
                                  "example": 36000.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "The track's title: its file name.",
                                  "example": "The First"
                                },
                                "contentUrl": {
                                  "type": "string",
                                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                                },
                                "mimeType": {
                                  "type": "string",
                                  "description": "The track's media type.",
                                  "example": "audio/mp4"
                                },
                                "codec": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The codec, if known.",
                                  "example": "aac"
                                },
                                "metadata": {
                                  "oneOf": [
                                    {
                                      "type": "object",
                                      "description": "The file's name, size and times.",
                                      "required": [
                                        "filename",
                                        "ext",
                                        "path",
                                        "relPath",
                                        "size",
                                        "mtimeMs",
                                        "ctimeMs",
                                        "birthtimeMs"
                                      ],
                                      "properties": {
                                        "filename": {
                                          "type": "string",
                                          "description": "The file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "ext": {
                                          "type": "string",
                                          "description": "The extension with its dot (`.m4b`).",
                                          "example": ".m4b"
                                        },
                                        "path": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "/the-first.m4b"
                                        },
                                        "relPath": {
                                          "type": "string",
                                          "description": "A display path: the file name.",
                                          "example": "the-first.m4b"
                                        },
                                        "size": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "The file's size in bytes.",
                                          "example": 100000,
                                          "minimum": 0
                                        },
                                        "mtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "ctimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        },
                                        "birthtimeMs": {
                                          "type": "integer",
                                          "format": "int64",
                                          "description": "When the file was stored, in epoch milliseconds.",
                                          "example": 1763600000000
                                        }
                                      }
                                    },
                                    {
                                      "type": "null"
                                    }
                                  ]
                                }
                              }
                            },
                            "description": "The tracks with their place in the book, when fetched expanded."
                          }
                        }
                      },
                      "numFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Files in the item.",
                        "example": 1,
                        "minimum": 0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in all its files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "libraryFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A file of an item, in the expanded item's `libraryFiles`.",
                          "required": [
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "fileType"
                          ],
                          "properties": {
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "fileType": {
                              "type": "string",
                              "description": "Always `audio`.",
                              "example": "audio"
                            }
                          }
                        },
                        "description": "The item's files, when the item is fetched expanded."
                      },
                      "userMediaProgress": {
                        "oneOf": [
                          {
                            "type": "object",
                            "description": "The patron's progress, when the app asked for it.",
                            "required": [
                              "id",
                              "userId",
                              "libraryItemId",
                              "mediaItemId",
                              "mediaItemType",
                              "duration",
                              "progress",
                              "currentTime",
                              "isFinished",
                              "hideFromContinueListening",
                              "lastUpdate",
                              "startedAt"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The progress id: the item id (one record per patron and item).",
                                "example": "li_8f14e45fceea467f"
                              },
                              "userId": {
                                "type": "string",
                                "description": "The patron's id.",
                                "example": "42"
                              },
                              "libraryItemId": {
                                "type": "string",
                                "description": "The item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "episodeId": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "mediaItemId": {
                                "type": "string",
                                "description": "The media id: the item id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "mediaItemType": {
                                "type": "string",
                                "description": "Always `book`.",
                                "example": "book"
                              },
                              "duration": {
                                "type": "number",
                                "format": "double",
                                "description": "The book's length in seconds, as last reported.",
                                "example": 36000.0
                              },
                              "progress": {
                                "type": "number",
                                "format": "double",
                                "description": "The share listened, from 0 to 1.",
                                "example": 0.05
                              },
                              "currentTime": {
                                "type": "number",
                                "format": "double",
                                "description": "Where the patron is, in seconds.",
                                "example": 1830.5
                              },
                              "isFinished": {
                                "type": "boolean",
                                "description": "Whether the patron finished it.",
                                "example": false
                              },
                              "hideFromContinueListening": {
                                "type": "boolean",
                                "description": "Whether it is hidden from continue listening.",
                                "example": false
                              },
                              "ebookLocation": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "Always null.",
                                "example": null
                              },
                              "ebookProgress": {
                                "type": [
                                  "number",
                                  "null"
                                ],
                                "format": "double",
                                "description": "Always null.",
                                "example": null
                              },
                              "lastUpdate": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the progress last changed, in epoch milliseconds.",
                                "example": 1763630000000
                              },
                              "startedAt": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the patron started, in epoch milliseconds.",
                                "example": 1763620000000
                              },
                              "finishedAt": {
                                "type": [
                                  "integer",
                                  "null"
                                ],
                                "format": "int64",
                                "description": "When the patron finished, in epoch milliseconds.",
                                "example": null
                              }
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      },
                      "seriesSequence": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item's place in a series, on a series' book list.",
                        "example": "1"
                      }
                    }
                  },
                  "description": "The items, in series order."
                }
              }
            },
            "description": "The author's series with their items, when asked for."
          }
        }
      },
      "description": "Matching authors."
    }
  }
}

Status 400: A query value is out of range, or the terms do not parse.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The search index is being built; retry.

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/stats

Adds up the library's items and their runtimes.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200Totals over the items the patron may see (runtimes over the first 20000). Body: LibraryStats (application/json)6 fields
    • totalItemsinteger (int64)requiredItems. At least 0.
    • totalAuthorsinteger (int64)requiredAuthors. At least 0.
    • totalGenresinteger (int64)requiredGenres. At least 0.
    • totalDurationnumber (double)requiredSeconds of audio in all.
    • numAudioTracksinteger (int64)requiredAudio tracks in all. At least 0.
    • totalSizeinteger (int64)requiredBytes in all: not counted. At least 0.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/stats' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/stats' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/stats",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/stats", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/stats")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Totals over the items the patron may see (runtimes over the first 20000).

{
  "totalItems": 1,
  "totalAuthors": 1,
  "totalGenres": 1,
  "totalDuration": 36000.0,
  "numAudioTracks": 1,
  "totalSize": 100000
}

Schema:

{
  "type": "object",
  "description": "`GET /api/libraries/{id}/stats`.",
  "required": [
    "totalItems",
    "totalAuthors",
    "totalGenres",
    "totalDuration",
    "numAudioTracks",
    "totalSize"
  ],
  "properties": {
    "totalItems": {
      "type": "integer",
      "format": "int64",
      "description": "Items.",
      "example": 1,
      "minimum": 0
    },
    "totalAuthors": {
      "type": "integer",
      "format": "int64",
      "description": "Authors.",
      "example": 1,
      "minimum": 0
    },
    "totalGenres": {
      "type": "integer",
      "format": "int64",
      "description": "Genres.",
      "example": 1,
      "minimum": 0
    },
    "totalDuration": {
      "type": "number",
      "format": "double",
      "description": "Seconds of audio in all.",
      "example": 36000.0
    },
    "numAudioTracks": {
      "type": "integer",
      "format": "int64",
      "description": "Audio tracks in all.",
      "example": 1,
      "minimum": 0
    },
    "totalSize": {
      "type": "integer",
      "format": "int64",
      "description": "Bytes in all: not counted.",
      "example": 100000,
      "minimum": 0
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/libraries/{id}/filterdata

Reads the library's filter values.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredLibrary id.

Responses

  • 200The filter values. Body: FilterData (application/json)14 fields
    • authorsarray of NamedRefrequiredAuthors with at least one item.
    • genresarray of stringrequiredGenres.
    • tagsarray of stringrequiredTags: none are shown.
    • seriesarray of NamedRefrequiredSeries with at least one item.
    • narratorsarray of stringrequiredNarrators.
    • languagesarray of stringrequiredLanguages.
    • publishersarray of stringrequiredPublishers.
    • publishedDecadesarray of stringrequiredDecades of publication: none are offered.
    • bookCountinteger (int64)requiredItems in the library. At least 0.
    • authorCountinteger (int64)requiredAuthors in the library. At least 0.
    • seriesCountinteger (int64)requiredSeries in the library. At least 0.
    • podcastCountinteger (int64)requiredAlways 0. At least 0.
    • numberEpisodesinteger (int64)requiredAlways 0. At least 0.
    • loadedAtinteger (int64)requiredWhen the values were read, in epoch milliseconds.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such library. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/libraries/<id>/filterdata' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/libraries/<id>/filterdata' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/libraries/<id>/filterdata",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/libraries/<id>/filterdata", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/libraries/<id>/filterdata")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The filter values.

{
  "authors": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author"
    }
  ],
  "genres": [
    "Fantasy"
  ],
  "tags": [],
  "series": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author"
    }
  ],
  "narrators": [
    "Nia Narrator"
  ],
  "languages": [
    "en-us"
  ],
  "publishers": [
    "Example Press"
  ],
  "publishedDecades": [
    "2020"
  ],
  "bookCount": 1,
  "authorCount": 1,
  "seriesCount": 1,
  "podcastCount": 0,
  "numberEpisodes": 0,
  "loadedAt": 1763630000000
}

Schema:

{
  "type": "object",
  "description": "The values an app offers as filters.",
  "required": [
    "authors",
    "genres",
    "tags",
    "series",
    "narrators",
    "languages",
    "publishers",
    "publishedDecades",
    "bookCount",
    "authorCount",
    "seriesCount",
    "podcastCount",
    "numberEpisodes",
    "loadedAt"
  ],
  "properties": {
    "authors": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An id and a name.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The entity's id.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "Its display name.",
            "example": "Ann Author"
          }
        }
      },
      "description": "Authors with at least one item."
    },
    "genres": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Genres.",
      "example": [
        "Fantasy"
      ]
    },
    "tags": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Tags: none are shown.",
      "example": []
    },
    "series": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An id and a name.",
        "required": [
          "id",
          "name"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The entity's id.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "Its display name.",
            "example": "Ann Author"
          }
        }
      },
      "description": "Series with at least one item."
    },
    "narrators": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Narrators.",
      "example": [
        "Nia Narrator"
      ]
    },
    "languages": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Languages.",
      "example": [
        "en-us"
      ]
    },
    "publishers": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Publishers.",
      "example": [
        "Example Press"
      ]
    },
    "publishedDecades": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "Decades of publication: none are offered.",
      "example": [
        "2020"
      ]
    },
    "bookCount": {
      "type": "integer",
      "format": "int64",
      "description": "Items in the library.",
      "example": 1,
      "minimum": 0
    },
    "authorCount": {
      "type": "integer",
      "format": "int64",
      "description": "Authors in the library.",
      "example": 1,
      "minimum": 0
    },
    "seriesCount": {
      "type": "integer",
      "format": "int64",
      "description": "Series in the library.",
      "example": 1,
      "minimum": 0
    },
    "podcastCount": {
      "type": "integer",
      "format": "int64",
      "description": "Always 0.",
      "example": 0,
      "minimum": 0
    },
    "numberEpisodes": {
      "type": "integer",
      "format": "int64",
      "description": "Always 0.",
      "example": 0,
      "minimum": 0
    },
    "loadedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the values were read, in epoch milliseconds.",
      "example": 1763630000000
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such library.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/series/{id}

Reads one series with its items and the patron's progress through it.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredSeries id.

Responses

  • 200The series. Body: Series (application/json)9 fields
    • idstringrequiredThe series id.
    • namestringrequiredIts name.
    • nameIgnorePrefixstringrequiredThe name for sorting.
    • descriptionstring or nullIts description: none.
    • addedAtinteger (int64)requiredWhen the library first saw it, in epoch milliseconds.
    • updatedAtinteger (int64)requiredWhen it last changed, in epoch milliseconds.
    • libraryIdstringrequiredThe library it is listed in.
    • booksarray of LibraryItem or nullIts items in series order, on lists.
    • progressSeriesProgress or nullThe patron's progress through it, when asked for.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such series the patron may see. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/series/<id>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/series/<id>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/series/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/series/<id>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/series/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The series.

{
  "id": "li_8f14e45fceea467f",
  "name": "Ann Author",
  "nameIgnorePrefix": "Saga, The",
  "description": "A short description.",
  "addedAt": 1763600000000,
  "updatedAt": 1763630000000,
  "libraryId": "bookclerk-library",
  "books": [
    {
      "id": "li_8f14e45fceea467f",
      "ino": "0",
      "oldLibraryItemId": null,
      "libraryId": "bookclerk-library",
      "folderId": "bookclerk-library",
      "path": "/the-first.m4b",
      "relPath": "the-first.m4b",
      "isFile": true,
      "mtimeMs": 1763600000000,
      "ctimeMs": 1763600000000,
      "birthtimeMs": 1763600000000,
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "id": "li_8f14e45fceea467f",
        "libraryItemId": "li_8f14e45fceea467f",
        "metadata": {
          "title": "The First",
          "titleIgnorePrefix": "First, The",
          "authors": [],
          "authorName": "Ann Author",
          "authorNameLF": "Author, Ann",
          "narrators": [
            "Nia Narrator"
          ],
          "narratorName": "Nia Narrator",
          "series": [],
          "seriesName": "The Saga #1",
          "genres": [
            "Fantasy"
          ],
          "explicit": false,
          "abridged": false
        },
        "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
        "tags": [],
        "numTracks": 1,
        "numAudioFiles": 1,
        "numChapters": 0,
        "duration": 36000.0,
        "size": 100000,
        "audioFiles": [],
        "chapters": [],
        "tracks": []
      },
      "numFiles": 1,
      "size": 100000,
      "libraryFiles": [
        {
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "fileType": "audio"
        }
      ],
      "userMediaProgress": {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      },
      "seriesSequence": "1"
    }
  ],
  "progress": {
    "libraryItemIds": [
      "li_8f14e45fceea467f"
    ],
    "libraryItemIdsFinished": [],
    "isFinished": false
  }
}

Schema:

{
  "type": "object",
  "description": "A series.",
  "required": [
    "id",
    "name",
    "nameIgnorePrefix",
    "addedAt",
    "updatedAt",
    "libraryId"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The series id.",
      "example": "li_8f14e45fceea467f"
    },
    "name": {
      "type": "string",
      "description": "Its name.",
      "example": "Ann Author"
    },
    "nameIgnorePrefix": {
      "type": "string",
      "description": "The name for sorting.",
      "example": "Saga, The"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Its description: none.",
      "example": "A short description."
    },
    "addedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the library first saw it, in epoch milliseconds.",
      "example": 1763600000000
    },
    "updatedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When it last changed, in epoch milliseconds.",
      "example": 1763630000000
    },
    "libraryId": {
      "type": "string",
      "description": "The library it is listed in.",
      "example": "bookclerk-library"
    },
    "books": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "description": "An item: an edition with a stored copy.",
        "required": [
          "id",
          "ino",
          "libraryId",
          "folderId",
          "path",
          "relPath",
          "isFile",
          "mtimeMs",
          "ctimeMs",
          "birthtimeMs",
          "addedAt",
          "updatedAt",
          "isMissing",
          "isInvalid",
          "mediaType",
          "media",
          "numFiles",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id: the edition id.",
            "example": "li_8f14e45fceea467f"
          },
          "ino": {
            "type": "string",
            "description": "The item's inode as apps expect one: the edition id again.",
            "example": "0"
          },
          "oldLibraryItemId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library the item is listed in.",
            "example": "bookclerk-library"
          },
          "folderId": {
            "type": "string",
            "description": "The folder id: the library id.",
            "example": "bookclerk-library"
          },
          "path": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "/the-first.m4b"
          },
          "relPath": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "the-first.m4b"
          },
          "isFile": {
            "type": "boolean",
            "description": "Always false: an item is a folder of tracks.",
            "example": true
          },
          "mtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy last changed, in epoch milliseconds.",
            "example": 1763600000000
          },
          "ctimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "birthtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the item joined the library, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When its record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "isMissing": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "isInvalid": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "media": {
            "type": "object",
            "description": "The book.",
            "required": [
              "id",
              "metadata",
              "tags",
              "numTracks",
              "numAudioFiles",
              "numChapters",
              "duration",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The media id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "libraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item id, when fetched expanded.",
                "example": "li_8f14e45fceea467f"
              },
              "metadata": {
                "type": "object",
                "description": "The book's metadata.",
                "required": [
                  "title",
                  "titleIgnorePrefix",
                  "authors",
                  "authorName",
                  "authorNameLF",
                  "narrators",
                  "narratorName",
                  "series",
                  "seriesName",
                  "genres",
                  "explicit",
                  "abridged"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title.",
                    "example": "The First"
                  },
                  "titleIgnorePrefix": {
                    "type": "string",
                    "description": "The title for sorting.",
                    "example": "First, The"
                  },
                  "subtitle": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The subtitle, if any.",
                    "example": "A Novel"
                  },
                  "authors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "An id and a name.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The entity's id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "Its display name.",
                          "example": "Ann Author"
                        }
                      }
                    },
                    "description": "The authors."
                  },
                  "authorName": {
                    "type": "string",
                    "description": "The authors' names joined with `, `.",
                    "example": "Ann Author"
                  },
                  "authorNameLF": {
                    "type": "string",
                    "description": "The authors' names, family name first, joined with `, `.",
                    "example": "Author, Ann"
                  },
                  "narrators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The narrators' names.",
                    "example": [
                      "Nia Narrator"
                    ]
                  },
                  "narratorName": {
                    "type": "string",
                    "description": "The narrators' names joined with `, `.",
                    "example": "Nia Narrator"
                  },
                  "series": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A series an item belongs to, with the item's place in it.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The series id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "The series name.",
                          "example": "Ann Author"
                        },
                        "sequence": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                          "example": "1"
                        }
                      }
                    },
                    "description": "The series the book is in."
                  },
                  "seriesName": {
                    "type": "string",
                    "description": "The series names with the book's place (`Name #2`), joined.",
                    "example": "The Saga #1"
                  },
                  "genres": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Genres.",
                    "example": [
                      "Fantasy"
                    ]
                  },
                  "publishedYear": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The year of publication, as a string (`\"2019\"`).",
                    "example": "2024"
                  },
                  "publishedDate": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The date of publication, if known.",
                    "example": "2024-03-01"
                  },
                  "publisher": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The publisher.",
                    "example": "Example Press"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description, as the library stores it.",
                    "example": "A short description."
                  },
                  "descriptionPlain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description with markup removed.",
                    "example": "A short description."
                  },
                  "isbn": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ISBN, if known.",
                    "example": "9780000000002"
                  },
                  "asin": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ASIN, if known.",
                    "example": "B000000000"
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The language.",
                    "example": "en-us"
                  },
                  "explicit": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "abridged": {
                    "type": "boolean",
                    "description": "Whether the edition is abridged.",
                    "example": false
                  }
                }
              },
              "coverPath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                "example": "/player/api/items/li_8f14e45fceea467f/cover"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tags: none.",
                "example": []
              },
              "numTracks": {
                "type": "integer",
                "format": "int64",
                "description": "Tracks in play order.",
                "example": 1,
                "minimum": 0
              },
              "numAudioFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Audio files.",
                "example": 1,
                "minimum": 0
              },
              "numChapters": {
                "type": "integer",
                "format": "int64",
                "description": "Chapters.",
                "example": 0,
                "minimum": 0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds.",
                "example": 36000.0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in its audio files.",
                "example": 100000,
                "minimum": 0
              },
              "audioFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An audio file of a book.",
                  "required": [
                    "index",
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "manuallyVerified",
                    "exclude",
                    "duration",
                    "chapters",
                    "metaTags",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "trackNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number the file's tags state: not read.",
                      "example": 1,
                      "minimum": 0
                    },
                    "discNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number the file's tags state: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "trackNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "discNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "manuallyVerified": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "exclude": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "format": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The container format, such as `mp4` or `mp3`.",
                      "example": "MP4A"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The file's length in seconds.",
                      "example": 36000.0
                    },
                    "bitRate": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Bits per second, if known.",
                      "example": 128000,
                      "minimum": 0
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The file's language, if known.",
                      "example": "en-us"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "timeBase": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The time base, if known.",
                      "example": "1/44100"
                    },
                    "channels": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Audio channels, if known.",
                      "example": 2,
                      "minimum": 0
                    },
                    "channelLayout": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel layout, if known.",
                      "example": "stereo"
                    },
                    "chapters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "Chapters embedded in the file: none are read."
                    },
                    "embeddedCoverArt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "metaTags": {
                      "type": "object",
                      "description": "Tags read from the file: none until the stored media probe reads\nthem."
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The file's media type, such as `audio/mp4`.",
                      "example": "audio/mp4"
                    }
                  }
                },
                "description": "The audio files, when fetched expanded."
              },
              "chapters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "The chapters, when fetched expanded."
              },
              "tracks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A track with its place in the book.",
                  "required": [
                    "index",
                    "startOffset",
                    "duration",
                    "title",
                    "contentUrl",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The track's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "startOffset": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the track starts in the book, in seconds.",
                      "example": 0.0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The track's length in seconds.",
                      "example": 36000.0
                    },
                    "title": {
                      "type": "string",
                      "description": "The track's title: its file name.",
                      "example": "The First"
                    },
                    "contentUrl": {
                      "type": "string",
                      "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The track's media type.",
                      "example": "audio/mp4"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "metadata": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                },
                "description": "The tracks with their place in the book, when fetched expanded."
              }
            }
          },
          "numFiles": {
            "type": "integer",
            "format": "int64",
            "description": "Files in the item.",
            "example": 1,
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes in all its files.",
            "example": 100000,
            "minimum": 0
          },
          "libraryFiles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A file of an item, in the expanded item's `libraryFiles`.",
              "required": [
                "ino",
                "metadata",
                "addedAt",
                "updatedAt",
                "fileType"
              ],
              "properties": {
                "ino": {
                  "type": "string",
                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                  "example": "0"
                },
                "metadata": {
                  "type": "object",
                  "description": "The file's name, size and times.",
                  "required": [
                    "filename",
                    "ext",
                    "path",
                    "relPath",
                    "size",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs"
                  ],
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The file name.",
                      "example": "the-first.m4b"
                    },
                    "ext": {
                      "type": "string",
                      "description": "The extension with its dot (`.m4b`).",
                      "example": ".m4b"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "the-first.m4b"
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's size in bytes.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    }
                  }
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "fileType": {
                  "type": "string",
                  "description": "Always `audio`.",
                  "example": "audio"
                }
              }
            },
            "description": "The item's files, when the item is fetched expanded."
          },
          "userMediaProgress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress, when the app asked for it.",
                "required": [
                  "id",
                  "userId",
                  "libraryItemId",
                  "mediaItemId",
                  "mediaItemType",
                  "duration",
                  "progress",
                  "currentTime",
                  "isFinished",
                  "hideFromContinueListening",
                  "lastUpdate",
                  "startedAt"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The progress id: the item id (one record per patron and item).",
                    "example": "li_8f14e45fceea467f"
                  },
                  "userId": {
                    "type": "string",
                    "description": "The patron's id.",
                    "example": "42"
                  },
                  "libraryItemId": {
                    "type": "string",
                    "description": "The item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "episodeId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "mediaItemId": {
                    "type": "string",
                    "description": "The media id: the item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "mediaItemType": {
                    "type": "string",
                    "description": "Always `book`.",
                    "example": "book"
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds, as last reported.",
                    "example": 36000.0
                  },
                  "progress": {
                    "type": "number",
                    "format": "double",
                    "description": "The share listened, from 0 to 1.",
                    "example": 0.05
                  },
                  "currentTime": {
                    "type": "number",
                    "format": "double",
                    "description": "Where the patron is, in seconds.",
                    "example": 1830.5
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished it.",
                    "example": false
                  },
                  "hideFromContinueListening": {
                    "type": "boolean",
                    "description": "Whether it is hidden from continue listening.",
                    "example": false
                  },
                  "ebookLocation": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "ebookProgress": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "format": "double",
                    "description": "Always null.",
                    "example": null
                  },
                  "lastUpdate": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the progress last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "startedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the patron started, in epoch milliseconds.",
                    "example": 1763620000000
                  },
                  "finishedAt": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "When the patron finished, in epoch milliseconds.",
                    "example": null
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "seriesSequence": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's place in a series, on a series' book list.",
            "example": "1"
          }
        }
      },
      "description": "Its items in series order, on lists."
    },
    "progress": {
      "oneOf": [
        {
          "type": "object",
          "description": "The patron's progress through it, when asked for.",
          "required": [
            "libraryItemIds",
            "libraryItemIdsFinished",
            "isFinished"
          ],
          "properties": {
            "libraryItemIds": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "The series' items, by id.",
              "example": [
                "li_8f14e45fceea467f"
              ]
            },
            "libraryItemIdsFinished": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Those the patron finished.",
              "example": []
            },
            "isFinished": {
              "type": "boolean",
              "description": "Whether the patron finished every one.",
              "example": false
            }
          }
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such series the patron may see.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/authors/{id}

Reads one author, with their items and series when asked for.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredAuthor id.
  • includequerystringitems and/or series.

Responses

  • 200The author. Body: Author (application/json)12 fields
    • idstringrequiredThe contributor id.
    • asinstring or nullAlways null.
    • namestringrequiredThe author's name.
    • lastFirststringrequiredThe name family name first.
    • descriptionstring or nullAlways null.
    • imagePathstring or nullAlways null: no author images.
    • libraryIdstringrequiredThe library it is listed in.
    • addedAtinteger (int64)requiredWhen the library first saw the author, in epoch milliseconds.
    • updatedAtinteger (int64)requiredWhen the record last changed, in epoch milliseconds.
    • numBooksinteger (int64)requiredItems by the author the patron can see. At least 0.
    • libraryItemsarray of LibraryItem or nullThe author's items, when asked for.
    • seriesarray of AuthorSeries or nullThe author's series with their items, when asked for.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such author the patron may see. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/authors/<id>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/authors/<id>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/authors/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/authors/<id>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/authors/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The author.

{
  "id": "li_8f14e45fceea467f",
  "asin": "B000000000",
  "name": "Ann Author",
  "lastFirst": "Author, Ann",
  "description": "A short description.",
  "imagePath": null,
  "libraryId": "bookclerk-library",
  "addedAt": 1763600000000,
  "updatedAt": 1763630000000,
  "numBooks": 1,
  "libraryItems": [
    {
      "id": "li_8f14e45fceea467f",
      "ino": "0",
      "oldLibraryItemId": null,
      "libraryId": "bookclerk-library",
      "folderId": "bookclerk-library",
      "path": "/the-first.m4b",
      "relPath": "the-first.m4b",
      "isFile": true,
      "mtimeMs": 1763600000000,
      "ctimeMs": 1763600000000,
      "birthtimeMs": 1763600000000,
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "id": "li_8f14e45fceea467f",
        "libraryItemId": "li_8f14e45fceea467f",
        "metadata": {
          "title": "The First",
          "titleIgnorePrefix": "First, The",
          "authors": [],
          "authorName": "Ann Author",
          "authorNameLF": "Author, Ann",
          "narrators": [
            "Nia Narrator"
          ],
          "narratorName": "Nia Narrator",
          "series": [],
          "seriesName": "The Saga #1",
          "genres": [
            "Fantasy"
          ],
          "explicit": false,
          "abridged": false
        },
        "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
        "tags": [],
        "numTracks": 1,
        "numAudioFiles": 1,
        "numChapters": 0,
        "duration": 36000.0,
        "size": 100000,
        "audioFiles": [],
        "chapters": [],
        "tracks": []
      },
      "numFiles": 1,
      "size": 100000,
      "libraryFiles": [
        {
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "fileType": "audio"
        }
      ],
      "userMediaProgress": {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      },
      "seriesSequence": "1"
    }
  ],
  "series": [
    {
      "id": "li_8f14e45fceea467f",
      "name": "Ann Author",
      "items": [
        {
          "id": "li_8f14e45fceea467f",
          "ino": "0",
          "libraryId": "bookclerk-library",
          "folderId": "bookclerk-library",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "isFile": true,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000,
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "isMissing": false,
          "isInvalid": false,
          "mediaType": "book",
          "media": {
            "id": "li_8f14e45fceea467f",
            "metadata": {
              "title": "The First",
              "titleIgnorePrefix": "First, The",
              "authors": [],
              "authorName": "Ann Author",
              "authorNameLF": "Author, Ann",
              "narrators": [
                "Nia Narrator"
              ],
              "narratorName": "Nia Narrator",
              "series": [],
              "seriesName": "The Saga #1",
              "genres": [
                "Fantasy"
              ],
              "explicit": false,
              "abridged": false
            },
            "tags": [],
            "numTracks": 1,
            "numAudioFiles": 1,
            "numChapters": 0,
            "duration": 36000.0,
            "size": 100000
          },
          "numFiles": 1,
          "size": 100000
        }
      ]
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "An author.",
  "required": [
    "id",
    "name",
    "lastFirst",
    "libraryId",
    "addedAt",
    "updatedAt",
    "numBooks"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The contributor id.",
      "example": "li_8f14e45fceea467f"
    },
    "asin": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": "B000000000"
    },
    "name": {
      "type": "string",
      "description": "The author's name.",
      "example": "Ann Author"
    },
    "lastFirst": {
      "type": "string",
      "description": "The name family name first.",
      "example": "Author, Ann"
    },
    "description": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": "A short description."
    },
    "imagePath": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null: no author images.",
      "example": null
    },
    "libraryId": {
      "type": "string",
      "description": "The library it is listed in.",
      "example": "bookclerk-library"
    },
    "addedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the library first saw the author, in epoch milliseconds.",
      "example": 1763600000000
    },
    "updatedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the record last changed, in epoch milliseconds.",
      "example": 1763630000000
    },
    "numBooks": {
      "type": "integer",
      "format": "int64",
      "description": "Items by the author the patron can see.",
      "example": 1,
      "minimum": 0
    },
    "libraryItems": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "description": "An item: an edition with a stored copy.",
        "required": [
          "id",
          "ino",
          "libraryId",
          "folderId",
          "path",
          "relPath",
          "isFile",
          "mtimeMs",
          "ctimeMs",
          "birthtimeMs",
          "addedAt",
          "updatedAt",
          "isMissing",
          "isInvalid",
          "mediaType",
          "media",
          "numFiles",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id: the edition id.",
            "example": "li_8f14e45fceea467f"
          },
          "ino": {
            "type": "string",
            "description": "The item's inode as apps expect one: the edition id again.",
            "example": "0"
          },
          "oldLibraryItemId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library the item is listed in.",
            "example": "bookclerk-library"
          },
          "folderId": {
            "type": "string",
            "description": "The folder id: the library id.",
            "example": "bookclerk-library"
          },
          "path": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "/the-first.m4b"
          },
          "relPath": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "the-first.m4b"
          },
          "isFile": {
            "type": "boolean",
            "description": "Always false: an item is a folder of tracks.",
            "example": true
          },
          "mtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy last changed, in epoch milliseconds.",
            "example": 1763600000000
          },
          "ctimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "birthtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the item joined the library, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When its record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "isMissing": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "isInvalid": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "media": {
            "type": "object",
            "description": "The book.",
            "required": [
              "id",
              "metadata",
              "tags",
              "numTracks",
              "numAudioFiles",
              "numChapters",
              "duration",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The media id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "libraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item id, when fetched expanded.",
                "example": "li_8f14e45fceea467f"
              },
              "metadata": {
                "type": "object",
                "description": "The book's metadata.",
                "required": [
                  "title",
                  "titleIgnorePrefix",
                  "authors",
                  "authorName",
                  "authorNameLF",
                  "narrators",
                  "narratorName",
                  "series",
                  "seriesName",
                  "genres",
                  "explicit",
                  "abridged"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title.",
                    "example": "The First"
                  },
                  "titleIgnorePrefix": {
                    "type": "string",
                    "description": "The title for sorting.",
                    "example": "First, The"
                  },
                  "subtitle": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The subtitle, if any.",
                    "example": "A Novel"
                  },
                  "authors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "An id and a name.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The entity's id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "Its display name.",
                          "example": "Ann Author"
                        }
                      }
                    },
                    "description": "The authors."
                  },
                  "authorName": {
                    "type": "string",
                    "description": "The authors' names joined with `, `.",
                    "example": "Ann Author"
                  },
                  "authorNameLF": {
                    "type": "string",
                    "description": "The authors' names, family name first, joined with `, `.",
                    "example": "Author, Ann"
                  },
                  "narrators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The narrators' names.",
                    "example": [
                      "Nia Narrator"
                    ]
                  },
                  "narratorName": {
                    "type": "string",
                    "description": "The narrators' names joined with `, `.",
                    "example": "Nia Narrator"
                  },
                  "series": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A series an item belongs to, with the item's place in it.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The series id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "The series name.",
                          "example": "Ann Author"
                        },
                        "sequence": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                          "example": "1"
                        }
                      }
                    },
                    "description": "The series the book is in."
                  },
                  "seriesName": {
                    "type": "string",
                    "description": "The series names with the book's place (`Name #2`), joined.",
                    "example": "The Saga #1"
                  },
                  "genres": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Genres.",
                    "example": [
                      "Fantasy"
                    ]
                  },
                  "publishedYear": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The year of publication, as a string (`\"2019\"`).",
                    "example": "2024"
                  },
                  "publishedDate": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The date of publication, if known.",
                    "example": "2024-03-01"
                  },
                  "publisher": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The publisher.",
                    "example": "Example Press"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description, as the library stores it.",
                    "example": "A short description."
                  },
                  "descriptionPlain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description with markup removed.",
                    "example": "A short description."
                  },
                  "isbn": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ISBN, if known.",
                    "example": "9780000000002"
                  },
                  "asin": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ASIN, if known.",
                    "example": "B000000000"
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The language.",
                    "example": "en-us"
                  },
                  "explicit": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "abridged": {
                    "type": "boolean",
                    "description": "Whether the edition is abridged.",
                    "example": false
                  }
                }
              },
              "coverPath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                "example": "/player/api/items/li_8f14e45fceea467f/cover"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tags: none.",
                "example": []
              },
              "numTracks": {
                "type": "integer",
                "format": "int64",
                "description": "Tracks in play order.",
                "example": 1,
                "minimum": 0
              },
              "numAudioFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Audio files.",
                "example": 1,
                "minimum": 0
              },
              "numChapters": {
                "type": "integer",
                "format": "int64",
                "description": "Chapters.",
                "example": 0,
                "minimum": 0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds.",
                "example": 36000.0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in its audio files.",
                "example": 100000,
                "minimum": 0
              },
              "audioFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An audio file of a book.",
                  "required": [
                    "index",
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "manuallyVerified",
                    "exclude",
                    "duration",
                    "chapters",
                    "metaTags",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "trackNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number the file's tags state: not read.",
                      "example": 1,
                      "minimum": 0
                    },
                    "discNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number the file's tags state: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "trackNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "discNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "manuallyVerified": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "exclude": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "format": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The container format, such as `mp4` or `mp3`.",
                      "example": "MP4A"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The file's length in seconds.",
                      "example": 36000.0
                    },
                    "bitRate": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Bits per second, if known.",
                      "example": 128000,
                      "minimum": 0
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The file's language, if known.",
                      "example": "en-us"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "timeBase": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The time base, if known.",
                      "example": "1/44100"
                    },
                    "channels": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Audio channels, if known.",
                      "example": 2,
                      "minimum": 0
                    },
                    "channelLayout": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel layout, if known.",
                      "example": "stereo"
                    },
                    "chapters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "Chapters embedded in the file: none are read."
                    },
                    "embeddedCoverArt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "metaTags": {
                      "type": "object",
                      "description": "Tags read from the file: none until the stored media probe reads\nthem."
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The file's media type, such as `audio/mp4`.",
                      "example": "audio/mp4"
                    }
                  }
                },
                "description": "The audio files, when fetched expanded."
              },
              "chapters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "The chapters, when fetched expanded."
              },
              "tracks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A track with its place in the book.",
                  "required": [
                    "index",
                    "startOffset",
                    "duration",
                    "title",
                    "contentUrl",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The track's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "startOffset": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the track starts in the book, in seconds.",
                      "example": 0.0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The track's length in seconds.",
                      "example": 36000.0
                    },
                    "title": {
                      "type": "string",
                      "description": "The track's title: its file name.",
                      "example": "The First"
                    },
                    "contentUrl": {
                      "type": "string",
                      "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The track's media type.",
                      "example": "audio/mp4"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "metadata": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                },
                "description": "The tracks with their place in the book, when fetched expanded."
              }
            }
          },
          "numFiles": {
            "type": "integer",
            "format": "int64",
            "description": "Files in the item.",
            "example": 1,
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes in all its files.",
            "example": 100000,
            "minimum": 0
          },
          "libraryFiles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A file of an item, in the expanded item's `libraryFiles`.",
              "required": [
                "ino",
                "metadata",
                "addedAt",
                "updatedAt",
                "fileType"
              ],
              "properties": {
                "ino": {
                  "type": "string",
                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                  "example": "0"
                },
                "metadata": {
                  "type": "object",
                  "description": "The file's name, size and times.",
                  "required": [
                    "filename",
                    "ext",
                    "path",
                    "relPath",
                    "size",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs"
                  ],
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The file name.",
                      "example": "the-first.m4b"
                    },
                    "ext": {
                      "type": "string",
                      "description": "The extension with its dot (`.m4b`).",
                      "example": ".m4b"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "the-first.m4b"
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's size in bytes.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    }
                  }
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "fileType": {
                  "type": "string",
                  "description": "Always `audio`.",
                  "example": "audio"
                }
              }
            },
            "description": "The item's files, when the item is fetched expanded."
          },
          "userMediaProgress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress, when the app asked for it.",
                "required": [
                  "id",
                  "userId",
                  "libraryItemId",
                  "mediaItemId",
                  "mediaItemType",
                  "duration",
                  "progress",
                  "currentTime",
                  "isFinished",
                  "hideFromContinueListening",
                  "lastUpdate",
                  "startedAt"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The progress id: the item id (one record per patron and item).",
                    "example": "li_8f14e45fceea467f"
                  },
                  "userId": {
                    "type": "string",
                    "description": "The patron's id.",
                    "example": "42"
                  },
                  "libraryItemId": {
                    "type": "string",
                    "description": "The item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "episodeId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "mediaItemId": {
                    "type": "string",
                    "description": "The media id: the item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "mediaItemType": {
                    "type": "string",
                    "description": "Always `book`.",
                    "example": "book"
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds, as last reported.",
                    "example": 36000.0
                  },
                  "progress": {
                    "type": "number",
                    "format": "double",
                    "description": "The share listened, from 0 to 1.",
                    "example": 0.05
                  },
                  "currentTime": {
                    "type": "number",
                    "format": "double",
                    "description": "Where the patron is, in seconds.",
                    "example": 1830.5
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished it.",
                    "example": false
                  },
                  "hideFromContinueListening": {
                    "type": "boolean",
                    "description": "Whether it is hidden from continue listening.",
                    "example": false
                  },
                  "ebookLocation": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "ebookProgress": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "format": "double",
                    "description": "Always null.",
                    "example": null
                  },
                  "lastUpdate": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the progress last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "startedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the patron started, in epoch milliseconds.",
                    "example": 1763620000000
                  },
                  "finishedAt": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "When the patron finished, in epoch milliseconds.",
                    "example": null
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "seriesSequence": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's place in a series, on a series' book list.",
            "example": "1"
          }
        }
      },
      "description": "The author's items, when asked for."
    },
    "series": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "description": "A series of an author's, with the author's items in it.",
        "required": [
          "id",
          "name",
          "items"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The series id.",
            "example": "li_8f14e45fceea467f"
          },
          "name": {
            "type": "string",
            "description": "The series name.",
            "example": "Ann Author"
          },
          "items": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "An item: an edition with a stored copy.",
              "required": [
                "id",
                "ino",
                "libraryId",
                "folderId",
                "path",
                "relPath",
                "isFile",
                "mtimeMs",
                "ctimeMs",
                "birthtimeMs",
                "addedAt",
                "updatedAt",
                "isMissing",
                "isInvalid",
                "mediaType",
                "media",
                "numFiles",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The item id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "ino": {
                  "type": "string",
                  "description": "The item's inode as apps expect one: the edition id again.",
                  "example": "0"
                },
                "oldLibraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "Always null.",
                  "example": null
                },
                "libraryId": {
                  "type": "string",
                  "description": "The library the item is listed in.",
                  "example": "bookclerk-library"
                },
                "folderId": {
                  "type": "string",
                  "description": "The folder id: the library id.",
                  "example": "bookclerk-library"
                },
                "path": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "/the-first.m4b"
                },
                "relPath": {
                  "type": "string",
                  "description": "A display path: the title.",
                  "example": "the-first.m4b"
                },
                "isFile": {
                  "type": "boolean",
                  "description": "Always false: an item is a folder of tracks.",
                  "example": true
                },
                "mtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy last changed, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "ctimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "birthtimeMs": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the copy was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the item joined the library, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When its record last changed, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "isMissing": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "isInvalid": {
                  "type": "boolean",
                  "description": "Always false.",
                  "example": false
                },
                "mediaType": {
                  "type": "string",
                  "description": "Always [`MEDIA_TYPE_BOOK`].",
                  "example": "book"
                },
                "media": {
                  "type": "object",
                  "description": "The book.",
                  "required": [
                    "id",
                    "metadata",
                    "tags",
                    "numTracks",
                    "numAudioFiles",
                    "numChapters",
                    "duration",
                    "size"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The media id: the edition id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "libraryItemId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item id, when fetched expanded.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The book's metadata.",
                      "required": [
                        "title",
                        "titleIgnorePrefix",
                        "authors",
                        "authorName",
                        "authorNameLF",
                        "narrators",
                        "narratorName",
                        "series",
                        "seriesName",
                        "genres",
                        "explicit",
                        "abridged"
                      ],
                      "properties": {
                        "title": {
                          "type": "string",
                          "description": "The title.",
                          "example": "The First"
                        },
                        "titleIgnorePrefix": {
                          "type": "string",
                          "description": "The title for sorting.",
                          "example": "First, The"
                        },
                        "subtitle": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The subtitle, if any.",
                          "example": "A Novel"
                        },
                        "authors": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "An id and a name.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The entity's id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "Its display name.",
                                "example": "Ann Author"
                              }
                            }
                          },
                          "description": "The authors."
                        },
                        "authorName": {
                          "type": "string",
                          "description": "The authors' names joined with `, `.",
                          "example": "Ann Author"
                        },
                        "authorNameLF": {
                          "type": "string",
                          "description": "The authors' names, family name first, joined with `, `.",
                          "example": "Author, Ann"
                        },
                        "narrators": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "The narrators' names.",
                          "example": [
                            "Nia Narrator"
                          ]
                        },
                        "narratorName": {
                          "type": "string",
                          "description": "The narrators' names joined with `, `.",
                          "example": "Nia Narrator"
                        },
                        "series": {
                          "type": "array",
                          "items": {
                            "type": "object",
                            "description": "A series an item belongs to, with the item's place in it.",
                            "required": [
                              "id",
                              "name"
                            ],
                            "properties": {
                              "id": {
                                "type": "string",
                                "description": "The series id.",
                                "example": "li_8f14e45fceea467f"
                              },
                              "name": {
                                "type": "string",
                                "description": "The series name.",
                                "example": "Ann Author"
                              },
                              "sequence": {
                                "type": [
                                  "string",
                                  "null"
                                ],
                                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                "example": "1"
                              }
                            }
                          },
                          "description": "The series the book is in."
                        },
                        "seriesName": {
                          "type": "string",
                          "description": "The series names with the book's place (`Name #2`), joined.",
                          "example": "The Saga #1"
                        },
                        "genres": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          },
                          "description": "Genres.",
                          "example": [
                            "Fantasy"
                          ]
                        },
                        "publishedYear": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The year of publication, as a string (`\"2019\"`).",
                          "example": "2024"
                        },
                        "publishedDate": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The date of publication, if known.",
                          "example": "2024-03-01"
                        },
                        "publisher": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The publisher.",
                          "example": "Example Press"
                        },
                        "description": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description, as the library stores it.",
                          "example": "A short description."
                        },
                        "descriptionPlain": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The description with markup removed.",
                          "example": "A short description."
                        },
                        "isbn": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ISBN, if known.",
                          "example": "9780000000002"
                        },
                        "asin": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The ASIN, if known.",
                          "example": "B000000000"
                        },
                        "language": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The language.",
                          "example": "en-us"
                        },
                        "explicit": {
                          "type": "boolean",
                          "description": "Always false.",
                          "example": false
                        },
                        "abridged": {
                          "type": "boolean",
                          "description": "Whether the edition is abridged.",
                          "example": false
                        }
                      }
                    },
                    "coverPath": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/cover"
                    },
                    "tags": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Tags: none.",
                      "example": []
                    },
                    "numTracks": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Tracks in play order.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numAudioFiles": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Audio files.",
                      "example": 1,
                      "minimum": 0
                    },
                    "numChapters": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Chapters.",
                      "example": 0,
                      "minimum": 0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds.",
                      "example": 36000.0
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "Bytes in its audio files.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "audioFiles": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "An audio file of a book.",
                        "required": [
                          "index",
                          "ino",
                          "metadata",
                          "addedAt",
                          "updatedAt",
                          "manuallyVerified",
                          "exclude",
                          "duration",
                          "chapters",
                          "metaTags",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "ino": {
                            "type": "string",
                            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                            "example": "0"
                          },
                          "metadata": {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          "addedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "updatedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "trackNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number the file's tags state: not read.",
                            "example": 1,
                            "minimum": 0
                          },
                          "discNumFromMeta": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number the file's tags state: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "trackNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The track number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "discNumFromFilename": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "The disc number in the file name: not read.",
                            "example": null,
                            "minimum": 0
                          },
                          "manuallyVerified": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "exclude": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "error": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "format": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The container format, such as `mp4` or `mp3`.",
                            "example": "MP4A"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The file's length in seconds.",
                            "example": 36000.0
                          },
                          "bitRate": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Bits per second, if known.",
                            "example": 128000,
                            "minimum": 0
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The file's language, if known.",
                            "example": "en-us"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "timeBase": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The time base, if known.",
                            "example": "1/44100"
                          },
                          "channels": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "Audio channels, if known.",
                            "example": 2,
                            "minimum": 0
                          },
                          "channelLayout": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The channel layout, if known.",
                            "example": "stereo"
                          },
                          "chapters": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A chapter of a book.",
                              "required": [
                                "id",
                                "start",
                                "end",
                                "title"
                              ],
                              "properties": {
                                "id": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The chapter's place, from 0.",
                                  "example": 1,
                                  "minimum": 0
                                },
                                "start": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it starts, in seconds.",
                                  "example": 0.0
                                },
                                "end": {
                                  "type": "number",
                                  "format": "double",
                                  "description": "Where it ends, in seconds.",
                                  "example": 600.0
                                },
                                "title": {
                                  "type": "string",
                                  "description": "Its title.",
                                  "example": "The First"
                                }
                              }
                            },
                            "description": "Chapters embedded in the file: none are read."
                          },
                          "embeddedCoverArt": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "metaTags": {
                            "type": "object",
                            "description": "Tags read from the file: none until the stored media probe reads\nthem."
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The file's media type, such as `audio/mp4`.",
                            "example": "audio/mp4"
                          }
                        }
                      },
                      "description": "The audio files, when fetched expanded."
                    },
                    "chapters": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "The chapters, when fetched expanded."
                    },
                    "tracks": {
                      "type": [
                        "array",
                        "null"
                      ],
                      "items": {
                        "type": "object",
                        "description": "A track with its place in the book.",
                        "required": [
                          "index",
                          "startOffset",
                          "duration",
                          "title",
                          "contentUrl",
                          "mimeType"
                        ],
                        "properties": {
                          "index": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The track's place in play order, from 1.",
                            "example": 1,
                            "minimum": 0
                          },
                          "startOffset": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the track starts in the book, in seconds.",
                            "example": 0.0
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The track's length in seconds.",
                            "example": 36000.0
                          },
                          "title": {
                            "type": "string",
                            "description": "The track's title: its file name.",
                            "example": "The First"
                          },
                          "contentUrl": {
                            "type": "string",
                            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                          },
                          "mimeType": {
                            "type": "string",
                            "description": "The track's media type.",
                            "example": "audio/mp4"
                          },
                          "codec": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The codec, if known.",
                            "example": "aac"
                          },
                          "metadata": {
                            "oneOf": [
                              {
                                "type": "object",
                                "description": "The file's name, size and times.",
                                "required": [
                                  "filename",
                                  "ext",
                                  "path",
                                  "relPath",
                                  "size",
                                  "mtimeMs",
                                  "ctimeMs",
                                  "birthtimeMs"
                                ],
                                "properties": {
                                  "filename": {
                                    "type": "string",
                                    "description": "The file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "ext": {
                                    "type": "string",
                                    "description": "The extension with its dot (`.m4b`).",
                                    "example": ".m4b"
                                  },
                                  "path": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "/the-first.m4b"
                                  },
                                  "relPath": {
                                    "type": "string",
                                    "description": "A display path: the file name.",
                                    "example": "the-first.m4b"
                                  },
                                  "size": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The file's size in bytes.",
                                    "example": 100000,
                                    "minimum": 0
                                  },
                                  "mtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "ctimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  },
                                  "birthtimeMs": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "When the file was stored, in epoch milliseconds.",
                                    "example": 1763600000000
                                  }
                                }
                              },
                              {
                                "type": "null"
                              }
                            ]
                          }
                        }
                      },
                      "description": "The tracks with their place in the book, when fetched expanded."
                    }
                  }
                },
                "numFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Files in the item.",
                  "example": 1,
                  "minimum": 0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in all its files.",
                  "example": 100000,
                  "minimum": 0
                },
                "libraryFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A file of an item, in the expanded item's `libraryFiles`.",
                    "required": [
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "fileType"
                    ],
                    "properties": {
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "fileType": {
                        "type": "string",
                        "description": "Always `audio`.",
                        "example": "audio"
                      }
                    }
                  },
                  "description": "The item's files, when the item is fetched expanded."
                },
                "userMediaProgress": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The patron's progress, when the app asked for it.",
                      "required": [
                        "id",
                        "userId",
                        "libraryItemId",
                        "mediaItemId",
                        "mediaItemType",
                        "duration",
                        "progress",
                        "currentTime",
                        "isFinished",
                        "hideFromContinueListening",
                        "lastUpdate",
                        "startedAt"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The progress id: the item id (one record per patron and item).",
                          "example": "li_8f14e45fceea467f"
                        },
                        "userId": {
                          "type": "string",
                          "description": "The patron's id.",
                          "example": "42"
                        },
                        "libraryItemId": {
                          "type": "string",
                          "description": "The item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "episodeId": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "mediaItemId": {
                          "type": "string",
                          "description": "The media id: the item id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "mediaItemType": {
                          "type": "string",
                          "description": "Always `book`.",
                          "example": "book"
                        },
                        "duration": {
                          "type": "number",
                          "format": "double",
                          "description": "The book's length in seconds, as last reported.",
                          "example": 36000.0
                        },
                        "progress": {
                          "type": "number",
                          "format": "double",
                          "description": "The share listened, from 0 to 1.",
                          "example": 0.05
                        },
                        "currentTime": {
                          "type": "number",
                          "format": "double",
                          "description": "Where the patron is, in seconds.",
                          "example": 1830.5
                        },
                        "isFinished": {
                          "type": "boolean",
                          "description": "Whether the patron finished it.",
                          "example": false
                        },
                        "hideFromContinueListening": {
                          "type": "boolean",
                          "description": "Whether it is hidden from continue listening.",
                          "example": false
                        },
                        "ebookLocation": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Always null.",
                          "example": null
                        },
                        "ebookProgress": {
                          "type": [
                            "number",
                            "null"
                          ],
                          "format": "double",
                          "description": "Always null.",
                          "example": null
                        },
                        "lastUpdate": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the progress last changed, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "startedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the patron started, in epoch milliseconds.",
                          "example": 1763620000000
                        },
                        "finishedAt": {
                          "type": [
                            "integer",
                            "null"
                          ],
                          "format": "int64",
                          "description": "When the patron finished, in epoch milliseconds.",
                          "example": null
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                },
                "seriesSequence": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item's place in a series, on a series' book list.",
                  "example": "1"
                }
              }
            },
            "description": "The items, in series order."
          }
        }
      },
      "description": "The author's series with their items, when asked for."
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such author the patron may see.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/items/{id}

Reads one item; expanded, with its tracks and files.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.
  • expandedqueryinteger (int32)1 to add tracks and files.
  • includequerystringprogress to add the patron's progress.

Responses

  • 200The item. Body: LibraryItem (application/json)22 fields
    • idstringrequiredThe item id: the edition id.
    • inostringrequiredThe item's inode as apps expect one: the edition id again.
    • oldLibraryItemIdstring or nullAlways null.
    • libraryIdstringrequiredThe library the item is listed in.
    • folderIdstringrequiredThe folder id: the library id.
    • pathstringrequiredA display path: the title.
    • relPathstringrequiredA display path: the title.
    • isFilebooleanrequiredAlways false: an item is a folder of tracks.
    • mtimeMsinteger (int64)requiredWhen the copy last changed, in epoch milliseconds.
    • ctimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.
    • birthtimeMsinteger (int64)requiredWhen the copy was stored, in epoch milliseconds.
    • addedAtinteger (int64)requiredWhen the item joined the library, in epoch milliseconds.
    • updatedAtinteger (int64)requiredWhen its record last changed, in epoch milliseconds.
    • isMissingbooleanrequiredAlways false.
    • isInvalidbooleanrequiredAlways false.
    • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
    • mediaBookMediarequiredThe book.
    • numFilesinteger (int64)requiredFiles in the item. At least 0.
    • sizeinteger (int64)requiredBytes in all its files. At least 0.
    • libraryFilesarray of LibraryFile or nullThe item's files, when the item is fetched expanded.
    • userMediaProgressMediaProgress or nullThe patron's progress, when the app asked for it.
    • seriesSequencestring or nullThe item's place in a series, on a series' book list.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item the patron may see. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/<id>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/items/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/items/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The item.

{
  "id": "li_8f14e45fceea467f",
  "ino": "0",
  "oldLibraryItemId": null,
  "libraryId": "bookclerk-library",
  "folderId": "bookclerk-library",
  "path": "/the-first.m4b",
  "relPath": "the-first.m4b",
  "isFile": true,
  "mtimeMs": 1763600000000,
  "ctimeMs": 1763600000000,
  "birthtimeMs": 1763600000000,
  "addedAt": 1763600000000,
  "updatedAt": 1763630000000,
  "isMissing": false,
  "isInvalid": false,
  "mediaType": "book",
  "media": {
    "id": "li_8f14e45fceea467f",
    "libraryItemId": "li_8f14e45fceea467f",
    "metadata": {
      "title": "The First",
      "titleIgnorePrefix": "First, The",
      "subtitle": "A Novel",
      "authors": [
        {
          "id": "li_8f14e45fceea467f",
          "name": "Ann Author"
        }
      ],
      "authorName": "Ann Author",
      "authorNameLF": "Author, Ann",
      "narrators": [
        "Nia Narrator"
      ],
      "narratorName": "Nia Narrator",
      "series": [
        {
          "id": "li_8f14e45fceea467f",
          "name": "Ann Author"
        }
      ],
      "seriesName": "The Saga #1",
      "genres": [
        "Fantasy"
      ],
      "publishedYear": "2024",
      "publishedDate": "2024-03-01",
      "publisher": "Example Press",
      "description": "A short description.",
      "descriptionPlain": "A short description.",
      "isbn": "9780000000002",
      "asin": "B000000000",
      "language": "en-us",
      "explicit": false,
      "abridged": false
    },
    "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
    "tags": [],
    "numTracks": 1,
    "numAudioFiles": 1,
    "numChapters": 0,
    "duration": 36000.0,
    "size": 100000,
    "audioFiles": [
      {
        "index": 1,
        "ino": "0",
        "metadata": {
          "filename": "the-first.m4b",
          "ext": ".m4b",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "size": 100000,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000
        },
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "trackNumFromMeta": 1,
        "discNumFromMeta": null,
        "trackNumFromFilename": null,
        "discNumFromFilename": null,
        "manuallyVerified": false,
        "exclude": false,
        "error": null,
        "format": "MP4A",
        "duration": 36000.0,
        "bitRate": 128000,
        "language": "en-us",
        "codec": "aac",
        "timeBase": "1/44100",
        "channels": 2,
        "channelLayout": "stereo",
        "chapters": [],
        "embeddedCoverArt": null,
        "metaTags": {},
        "mimeType": "audio/mp4"
      }
    ],
    "chapters": [
      {
        "id": 1,
        "start": 0.0,
        "end": 600.0,
        "title": "The First"
      }
    ],
    "tracks": [
      {
        "index": 1,
        "startOffset": 0.0,
        "duration": 36000.0,
        "title": "The First",
        "contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
        "mimeType": "audio/mp4",
        "codec": "aac",
        "metadata": {
          "filename": "the-first.m4b",
          "ext": ".m4b",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "size": 100000,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000
        }
      }
    ]
  },
  "numFiles": 1,
  "size": 100000,
  "libraryFiles": [
    {
      "ino": "0",
      "metadata": {
        "filename": "the-first.m4b",
        "ext": ".m4b",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "size": 100000,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000
      },
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "fileType": "audio"
    }
  ],
  "userMediaProgress": {
    "id": "li_8f14e45fceea467f",
    "userId": "42",
    "libraryItemId": "li_8f14e45fceea467f",
    "episodeId": null,
    "mediaItemId": "li_8f14e45fceea467f",
    "mediaItemType": "book",
    "duration": 36000.0,
    "progress": 0.05,
    "currentTime": 1830.5,
    "isFinished": false,
    "hideFromContinueListening": false,
    "ebookLocation": null,
    "ebookProgress": null,
    "lastUpdate": 1763630000000,
    "startedAt": 1763620000000,
    "finishedAt": null
  },
  "seriesSequence": "1"
}

Schema:

{
  "type": "object",
  "description": "An item: an edition with a stored copy.",
  "required": [
    "id",
    "ino",
    "libraryId",
    "folderId",
    "path",
    "relPath",
    "isFile",
    "mtimeMs",
    "ctimeMs",
    "birthtimeMs",
    "addedAt",
    "updatedAt",
    "isMissing",
    "isInvalid",
    "mediaType",
    "media",
    "numFiles",
    "size"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The item id: the edition id.",
      "example": "li_8f14e45fceea467f"
    },
    "ino": {
      "type": "string",
      "description": "The item's inode as apps expect one: the edition id again.",
      "example": "0"
    },
    "oldLibraryItemId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": null
    },
    "libraryId": {
      "type": "string",
      "description": "The library the item is listed in.",
      "example": "bookclerk-library"
    },
    "folderId": {
      "type": "string",
      "description": "The folder id: the library id.",
      "example": "bookclerk-library"
    },
    "path": {
      "type": "string",
      "description": "A display path: the title.",
      "example": "/the-first.m4b"
    },
    "relPath": {
      "type": "string",
      "description": "A display path: the title.",
      "example": "the-first.m4b"
    },
    "isFile": {
      "type": "boolean",
      "description": "Always false: an item is a folder of tracks.",
      "example": true
    },
    "mtimeMs": {
      "type": "integer",
      "format": "int64",
      "description": "When the copy last changed, in epoch milliseconds.",
      "example": 1763600000000
    },
    "ctimeMs": {
      "type": "integer",
      "format": "int64",
      "description": "When the copy was stored, in epoch milliseconds.",
      "example": 1763600000000
    },
    "birthtimeMs": {
      "type": "integer",
      "format": "int64",
      "description": "When the copy was stored, in epoch milliseconds.",
      "example": 1763600000000
    },
    "addedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the item joined the library, in epoch milliseconds.",
      "example": 1763600000000
    },
    "updatedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When its record last changed, in epoch milliseconds.",
      "example": 1763630000000
    },
    "isMissing": {
      "type": "boolean",
      "description": "Always false.",
      "example": false
    },
    "isInvalid": {
      "type": "boolean",
      "description": "Always false.",
      "example": false
    },
    "mediaType": {
      "type": "string",
      "description": "Always [`MEDIA_TYPE_BOOK`].",
      "example": "book"
    },
    "media": {
      "type": "object",
      "description": "The book.",
      "required": [
        "id",
        "metadata",
        "tags",
        "numTracks",
        "numAudioFiles",
        "numChapters",
        "duration",
        "size"
      ],
      "properties": {
        "id": {
          "type": "string",
          "description": "The media id: the edition id.",
          "example": "li_8f14e45fceea467f"
        },
        "libraryItemId": {
          "type": [
            "string",
            "null"
          ],
          "description": "The item id, when fetched expanded.",
          "example": "li_8f14e45fceea467f"
        },
        "metadata": {
          "type": "object",
          "description": "The book's metadata.",
          "required": [
            "title",
            "titleIgnorePrefix",
            "authors",
            "authorName",
            "authorNameLF",
            "narrators",
            "narratorName",
            "series",
            "seriesName",
            "genres",
            "explicit",
            "abridged"
          ],
          "properties": {
            "title": {
              "type": "string",
              "description": "The title.",
              "example": "The First"
            },
            "titleIgnorePrefix": {
              "type": "string",
              "description": "The title for sorting.",
              "example": "First, The"
            },
            "subtitle": {
              "type": [
                "string",
                "null"
              ],
              "description": "The subtitle, if any.",
              "example": "A Novel"
            },
            "authors": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "An id and a name.",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The entity's id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "name": {
                    "type": "string",
                    "description": "Its display name.",
                    "example": "Ann Author"
                  }
                }
              },
              "description": "The authors."
            },
            "authorName": {
              "type": "string",
              "description": "The authors' names joined with `, `.",
              "example": "Ann Author"
            },
            "authorNameLF": {
              "type": "string",
              "description": "The authors' names, family name first, joined with `, `.",
              "example": "Author, Ann"
            },
            "narrators": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "The narrators' names.",
              "example": [
                "Nia Narrator"
              ]
            },
            "narratorName": {
              "type": "string",
              "description": "The narrators' names joined with `, `.",
              "example": "Nia Narrator"
            },
            "series": {
              "type": "array",
              "items": {
                "type": "object",
                "description": "A series an item belongs to, with the item's place in it.",
                "required": [
                  "id",
                  "name"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The series id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "name": {
                    "type": "string",
                    "description": "The series name.",
                    "example": "Ann Author"
                  },
                  "sequence": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                    "example": "1"
                  }
                }
              },
              "description": "The series the book is in."
            },
            "seriesName": {
              "type": "string",
              "description": "The series names with the book's place (`Name #2`), joined.",
              "example": "The Saga #1"
            },
            "genres": {
              "type": "array",
              "items": {
                "type": "string"
              },
              "description": "Genres.",
              "example": [
                "Fantasy"
              ]
            },
            "publishedYear": {
              "type": [
                "string",
                "null"
              ],
              "description": "The year of publication, as a string (`\"2019\"`).",
              "example": "2024"
            },
            "publishedDate": {
              "type": [
                "string",
                "null"
              ],
              "description": "The date of publication, if known.",
              "example": "2024-03-01"
            },
            "publisher": {
              "type": [
                "string",
                "null"
              ],
              "description": "The publisher.",
              "example": "Example Press"
            },
            "description": {
              "type": [
                "string",
                "null"
              ],
              "description": "The description, as the library stores it.",
              "example": "A short description."
            },
            "descriptionPlain": {
              "type": [
                "string",
                "null"
              ],
              "description": "The description with markup removed.",
              "example": "A short description."
            },
            "isbn": {
              "type": [
                "string",
                "null"
              ],
              "description": "The ISBN, if known.",
              "example": "9780000000002"
            },
            "asin": {
              "type": [
                "string",
                "null"
              ],
              "description": "The ASIN, if known.",
              "example": "B000000000"
            },
            "language": {
              "type": [
                "string",
                "null"
              ],
              "description": "The language.",
              "example": "en-us"
            },
            "explicit": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "abridged": {
              "type": "boolean",
              "description": "Whether the edition is abridged.",
              "example": false
            }
          }
        },
        "coverPath": {
          "type": [
            "string",
            "null"
          ],
          "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
          "example": "/player/api/items/li_8f14e45fceea467f/cover"
        },
        "tags": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Tags: none.",
          "example": []
        },
        "numTracks": {
          "type": "integer",
          "format": "int64",
          "description": "Tracks in play order.",
          "example": 1,
          "minimum": 0
        },
        "numAudioFiles": {
          "type": "integer",
          "format": "int64",
          "description": "Audio files.",
          "example": 1,
          "minimum": 0
        },
        "numChapters": {
          "type": "integer",
          "format": "int64",
          "description": "Chapters.",
          "example": 0,
          "minimum": 0
        },
        "duration": {
          "type": "number",
          "format": "double",
          "description": "The book's length in seconds.",
          "example": 36000.0
        },
        "size": {
          "type": "integer",
          "format": "int64",
          "description": "Bytes in its audio files.",
          "example": 100000,
          "minimum": 0
        },
        "audioFiles": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "description": "An audio file of a book.",
            "required": [
              "index",
              "ino",
              "metadata",
              "addedAt",
              "updatedAt",
              "manuallyVerified",
              "exclude",
              "duration",
              "chapters",
              "metaTags",
              "mimeType"
            ],
            "properties": {
              "index": {
                "type": "integer",
                "format": "int64",
                "description": "The file's place in play order, from 1.",
                "example": 1,
                "minimum": 0
              },
              "ino": {
                "type": "string",
                "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                "example": "0"
              },
              "metadata": {
                "type": "object",
                "description": "The file's name, size and times.",
                "required": [
                  "filename",
                  "ext",
                  "path",
                  "relPath",
                  "size",
                  "mtimeMs",
                  "ctimeMs",
                  "birthtimeMs"
                ],
                "properties": {
                  "filename": {
                    "type": "string",
                    "description": "The file name.",
                    "example": "the-first.m4b"
                  },
                  "ext": {
                    "type": "string",
                    "description": "The extension with its dot (`.m4b`).",
                    "example": ".m4b"
                  },
                  "path": {
                    "type": "string",
                    "description": "A display path: the file name.",
                    "example": "/the-first.m4b"
                  },
                  "relPath": {
                    "type": "string",
                    "description": "A display path: the file name.",
                    "example": "the-first.m4b"
                  },
                  "size": {
                    "type": "integer",
                    "format": "int64",
                    "description": "The file's size in bytes.",
                    "example": 100000,
                    "minimum": 0
                  },
                  "mtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "ctimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "birthtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  }
                }
              },
              "addedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the file was stored, in epoch milliseconds.",
                "example": 1763600000000
              },
              "updatedAt": {
                "type": "integer",
                "format": "int64",
                "description": "When the file was stored, in epoch milliseconds.",
                "example": 1763630000000
              },
              "trackNumFromMeta": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "The track number the file's tags state: not read.",
                "example": 1,
                "minimum": 0
              },
              "discNumFromMeta": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "The disc number the file's tags state: not read.",
                "example": null,
                "minimum": 0
              },
              "trackNumFromFilename": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "The track number in the file name: not read.",
                "example": null,
                "minimum": 0
              },
              "discNumFromFilename": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "The disc number in the file name: not read.",
                "example": null,
                "minimum": 0
              },
              "manuallyVerified": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "exclude": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "error": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "format": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The container format, such as `mp4` or `mp3`.",
                "example": "MP4A"
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The file's length in seconds.",
                "example": 36000.0
              },
              "bitRate": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "Bits per second, if known.",
                "example": 128000,
                "minimum": 0
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The file's language, if known.",
                "example": "en-us"
              },
              "codec": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The codec, if known.",
                "example": "aac"
              },
              "timeBase": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The time base, if known.",
                "example": "1/44100"
              },
              "channels": {
                "type": [
                  "integer",
                  "null"
                ],
                "format": "int64",
                "description": "Audio channels, if known.",
                "example": 2,
                "minimum": 0
              },
              "channelLayout": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The channel layout, if known.",
                "example": "stereo"
              },
              "chapters": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "Chapters embedded in the file: none are read."
              },
              "embeddedCoverArt": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "Always null.",
                "example": null
              },
              "metaTags": {
                "type": "object",
                "description": "Tags read from the file: none until the stored media probe reads\nthem."
              },
              "mimeType": {
                "type": "string",
                "description": "The file's media type, such as `audio/mp4`.",
                "example": "audio/mp4"
              }
            }
          },
          "description": "The audio files, when fetched expanded."
        },
        "chapters": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "description": "A chapter of a book.",
            "required": [
              "id",
              "start",
              "end",
              "title"
            ],
            "properties": {
              "id": {
                "type": "integer",
                "format": "int64",
                "description": "The chapter's place, from 0.",
                "example": 1,
                "minimum": 0
              },
              "start": {
                "type": "number",
                "format": "double",
                "description": "Where it starts, in seconds.",
                "example": 0.0
              },
              "end": {
                "type": "number",
                "format": "double",
                "description": "Where it ends, in seconds.",
                "example": 600.0
              },
              "title": {
                "type": "string",
                "description": "Its title.",
                "example": "The First"
              }
            }
          },
          "description": "The chapters, when fetched expanded."
        },
        "tracks": {
          "type": [
            "array",
            "null"
          ],
          "items": {
            "type": "object",
            "description": "A track with its place in the book.",
            "required": [
              "index",
              "startOffset",
              "duration",
              "title",
              "contentUrl",
              "mimeType"
            ],
            "properties": {
              "index": {
                "type": "integer",
                "format": "int64",
                "description": "The track's place in play order, from 1.",
                "example": 1,
                "minimum": 0
              },
              "startOffset": {
                "type": "number",
                "format": "double",
                "description": "Where the track starts in the book, in seconds.",
                "example": 0.0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The track's length in seconds.",
                "example": 36000.0
              },
              "title": {
                "type": "string",
                "description": "The track's title: its file name.",
                "example": "The First"
              },
              "contentUrl": {
                "type": "string",
                "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                "example": "/player/api/items/li_8f14e45fceea467f/file/0"
              },
              "mimeType": {
                "type": "string",
                "description": "The track's media type.",
                "example": "audio/mp4"
              },
              "codec": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The codec, if known.",
                "example": "aac"
              },
              "metadata": {
                "oneOf": [
                  {
                    "type": "object",
                    "description": "The file's name, size and times.",
                    "required": [
                      "filename",
                      "ext",
                      "path",
                      "relPath",
                      "size",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs"
                    ],
                    "properties": {
                      "filename": {
                        "type": "string",
                        "description": "The file name.",
                        "example": "the-first.m4b"
                      },
                      "ext": {
                        "type": "string",
                        "description": "The extension with its dot (`.m4b`).",
                        "example": ".m4b"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the file name.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the file name.",
                        "example": "the-first.m4b"
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "The file's size in bytes.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      }
                    }
                  },
                  {
                    "type": "null"
                  }
                ]
              }
            }
          },
          "description": "The tracks with their place in the book, when fetched expanded."
        }
      }
    },
    "numFiles": {
      "type": "integer",
      "format": "int64",
      "description": "Files in the item.",
      "example": 1,
      "minimum": 0
    },
    "size": {
      "type": "integer",
      "format": "int64",
      "description": "Bytes in all its files.",
      "example": 100000,
      "minimum": 0
    },
    "libraryFiles": {
      "type": [
        "array",
        "null"
      ],
      "items": {
        "type": "object",
        "description": "A file of an item, in the expanded item's `libraryFiles`.",
        "required": [
          "ino",
          "metadata",
          "addedAt",
          "updatedAt",
          "fileType"
        ],
        "properties": {
          "ino": {
            "type": "string",
            "description": "The file's `ino` ([`crate::ids::file_ino`]).",
            "example": "0"
          },
          "metadata": {
            "type": "object",
            "description": "The file's name, size and times.",
            "required": [
              "filename",
              "ext",
              "path",
              "relPath",
              "size",
              "mtimeMs",
              "ctimeMs",
              "birthtimeMs"
            ],
            "properties": {
              "filename": {
                "type": "string",
                "description": "The file name.",
                "example": "the-first.m4b"
              },
              "ext": {
                "type": "string",
                "description": "The extension with its dot (`.m4b`).",
                "example": ".m4b"
              },
              "path": {
                "type": "string",
                "description": "A display path: the file name.",
                "example": "/the-first.m4b"
              },
              "relPath": {
                "type": "string",
                "description": "A display path: the file name.",
                "example": "the-first.m4b"
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "The file's size in bytes.",
                "example": 100000,
                "minimum": 0
              },
              "mtimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the file was stored, in epoch milliseconds.",
                "example": 1763600000000
              },
              "ctimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the file was stored, in epoch milliseconds.",
                "example": 1763600000000
              },
              "birthtimeMs": {
                "type": "integer",
                "format": "int64",
                "description": "When the file was stored, in epoch milliseconds.",
                "example": 1763600000000
              }
            }
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the file was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the file was stored, in epoch milliseconds.",
            "example": 1763630000000
          },
          "fileType": {
            "type": "string",
            "description": "Always `audio`.",
            "example": "audio"
          }
        }
      },
      "description": "The item's files, when the item is fetched expanded."
    },
    "userMediaProgress": {
      "oneOf": [
        {
          "type": "object",
          "description": "The patron's progress, when the app asked for it.",
          "required": [
            "id",
            "userId",
            "libraryItemId",
            "mediaItemId",
            "mediaItemType",
            "duration",
            "progress",
            "currentTime",
            "isFinished",
            "hideFromContinueListening",
            "lastUpdate",
            "startedAt"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The progress id: the item id (one record per patron and item).",
              "example": "li_8f14e45fceea467f"
            },
            "userId": {
              "type": "string",
              "description": "The patron's id.",
              "example": "42"
            },
            "libraryItemId": {
              "type": "string",
              "description": "The item id.",
              "example": "li_8f14e45fceea467f"
            },
            "episodeId": {
              "type": [
                "string",
                "null"
              ],
              "description": "Always null.",
              "example": null
            },
            "mediaItemId": {
              "type": "string",
              "description": "The media id: the item id.",
              "example": "li_8f14e45fceea467f"
            },
            "mediaItemType": {
              "type": "string",
              "description": "Always `book`.",
              "example": "book"
            },
            "duration": {
              "type": "number",
              "format": "double",
              "description": "The book's length in seconds, as last reported.",
              "example": 36000.0
            },
            "progress": {
              "type": "number",
              "format": "double",
              "description": "The share listened, from 0 to 1.",
              "example": 0.05
            },
            "currentTime": {
              "type": "number",
              "format": "double",
              "description": "Where the patron is, in seconds.",
              "example": 1830.5
            },
            "isFinished": {
              "type": "boolean",
              "description": "Whether the patron finished it.",
              "example": false
            },
            "hideFromContinueListening": {
              "type": "boolean",
              "description": "Whether it is hidden from continue listening.",
              "example": false
            },
            "ebookLocation": {
              "type": [
                "string",
                "null"
              ],
              "description": "Always null.",
              "example": null
            },
            "ebookProgress": {
              "type": [
                "number",
                "null"
              ],
              "format": "double",
              "description": "Always null.",
              "example": null
            },
            "lastUpdate": {
              "type": "integer",
              "format": "int64",
              "description": "When the progress last changed, in epoch milliseconds.",
              "example": 1763630000000
            },
            "startedAt": {
              "type": "integer",
              "format": "int64",
              "description": "When the patron started, in epoch milliseconds.",
              "example": 1763620000000
            },
            "finishedAt": {
              "type": [
                "integer",
                "null"
              ],
              "format": "int64",
              "description": "When the patron finished, in epoch milliseconds.",
              "example": null
            }
          }
        },
        {
          "type": "null"
        }
      ]
    },
    "seriesSequence": {
      "type": [
        "string",
        "null"
      ],
      "description": "The item's place in a series, on a series' book list.",
      "example": "1"
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item the patron may see.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/items/batch/get

Reads several items at once.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Request body

The items to read, at most 100.

application/json: BatchGetBody

  • libraryItemIdsarray of stringrequiredThe items, at most 100.

Responses

  • 200The items the patron may see, in the given order. Body: LibraryItems (application/json)1 field
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/batch/get' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{"libraryItemIds": ["li_8f14e45fceea467f"]}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/batch/get' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{"libraryItemIds": ["li_8f14e45fceea467f"]}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/items/batch/get",
    headers={"Authorization": "Bearer <playerToken>"},
    json={"libraryItemIds": ["li_8f14e45fceea467f"]},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/batch/get", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"libraryItemIds": ["li_8f14e45fceea467f"]}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/items/batch/get")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({"libraryItemIds": ["li_8f14e45fceea467f"]}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The items the patron may see, in the given order.

{
  "libraryItems": [
    {
      "id": "li_8f14e45fceea467f",
      "ino": "0",
      "oldLibraryItemId": null,
      "libraryId": "bookclerk-library",
      "folderId": "bookclerk-library",
      "path": "/the-first.m4b",
      "relPath": "the-first.m4b",
      "isFile": true,
      "mtimeMs": 1763600000000,
      "ctimeMs": 1763600000000,
      "birthtimeMs": 1763600000000,
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "id": "li_8f14e45fceea467f",
        "libraryItemId": "li_8f14e45fceea467f",
        "metadata": {
          "title": "The First",
          "titleIgnorePrefix": "First, The",
          "authors": [],
          "authorName": "Ann Author",
          "authorNameLF": "Author, Ann",
          "narrators": [
            "Nia Narrator"
          ],
          "narratorName": "Nia Narrator",
          "series": [],
          "seriesName": "The Saga #1",
          "genres": [
            "Fantasy"
          ],
          "explicit": false,
          "abridged": false
        },
        "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
        "tags": [],
        "numTracks": 1,
        "numAudioFiles": 1,
        "numChapters": 0,
        "duration": 36000.0,
        "size": 100000,
        "audioFiles": [],
        "chapters": [],
        "tracks": []
      },
      "numFiles": 1,
      "size": 100000,
      "libraryFiles": [
        {
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "fileType": "audio"
        }
      ],
      "userMediaProgress": {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      },
      "seriesSequence": "1"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`{ \"libraryItems\": [...] }`: in-progress items and batch reads.",
  "required": [
    "libraryItems"
  ],
  "properties": {
    "libraryItems": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An item: an edition with a stored copy.",
        "required": [
          "id",
          "ino",
          "libraryId",
          "folderId",
          "path",
          "relPath",
          "isFile",
          "mtimeMs",
          "ctimeMs",
          "birthtimeMs",
          "addedAt",
          "updatedAt",
          "isMissing",
          "isInvalid",
          "mediaType",
          "media",
          "numFiles",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id: the edition id.",
            "example": "li_8f14e45fceea467f"
          },
          "ino": {
            "type": "string",
            "description": "The item's inode as apps expect one: the edition id again.",
            "example": "0"
          },
          "oldLibraryItemId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library the item is listed in.",
            "example": "bookclerk-library"
          },
          "folderId": {
            "type": "string",
            "description": "The folder id: the library id.",
            "example": "bookclerk-library"
          },
          "path": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "/the-first.m4b"
          },
          "relPath": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "the-first.m4b"
          },
          "isFile": {
            "type": "boolean",
            "description": "Always false: an item is a folder of tracks.",
            "example": true
          },
          "mtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy last changed, in epoch milliseconds.",
            "example": 1763600000000
          },
          "ctimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "birthtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the item joined the library, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When its record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "isMissing": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "isInvalid": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "media": {
            "type": "object",
            "description": "The book.",
            "required": [
              "id",
              "metadata",
              "tags",
              "numTracks",
              "numAudioFiles",
              "numChapters",
              "duration",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The media id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "libraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item id, when fetched expanded.",
                "example": "li_8f14e45fceea467f"
              },
              "metadata": {
                "type": "object",
                "description": "The book's metadata.",
                "required": [
                  "title",
                  "titleIgnorePrefix",
                  "authors",
                  "authorName",
                  "authorNameLF",
                  "narrators",
                  "narratorName",
                  "series",
                  "seriesName",
                  "genres",
                  "explicit",
                  "abridged"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title.",
                    "example": "The First"
                  },
                  "titleIgnorePrefix": {
                    "type": "string",
                    "description": "The title for sorting.",
                    "example": "First, The"
                  },
                  "subtitle": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The subtitle, if any.",
                    "example": "A Novel"
                  },
                  "authors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "An id and a name.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The entity's id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "Its display name.",
                          "example": "Ann Author"
                        }
                      }
                    },
                    "description": "The authors."
                  },
                  "authorName": {
                    "type": "string",
                    "description": "The authors' names joined with `, `.",
                    "example": "Ann Author"
                  },
                  "authorNameLF": {
                    "type": "string",
                    "description": "The authors' names, family name first, joined with `, `.",
                    "example": "Author, Ann"
                  },
                  "narrators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The narrators' names.",
                    "example": [
                      "Nia Narrator"
                    ]
                  },
                  "narratorName": {
                    "type": "string",
                    "description": "The narrators' names joined with `, `.",
                    "example": "Nia Narrator"
                  },
                  "series": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A series an item belongs to, with the item's place in it.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The series id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "The series name.",
                          "example": "Ann Author"
                        },
                        "sequence": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                          "example": "1"
                        }
                      }
                    },
                    "description": "The series the book is in."
                  },
                  "seriesName": {
                    "type": "string",
                    "description": "The series names with the book's place (`Name #2`), joined.",
                    "example": "The Saga #1"
                  },
                  "genres": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Genres.",
                    "example": [
                      "Fantasy"
                    ]
                  },
                  "publishedYear": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The year of publication, as a string (`\"2019\"`).",
                    "example": "2024"
                  },
                  "publishedDate": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The date of publication, if known.",
                    "example": "2024-03-01"
                  },
                  "publisher": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The publisher.",
                    "example": "Example Press"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description, as the library stores it.",
                    "example": "A short description."
                  },
                  "descriptionPlain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description with markup removed.",
                    "example": "A short description."
                  },
                  "isbn": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ISBN, if known.",
                    "example": "9780000000002"
                  },
                  "asin": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ASIN, if known.",
                    "example": "B000000000"
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The language.",
                    "example": "en-us"
                  },
                  "explicit": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "abridged": {
                    "type": "boolean",
                    "description": "Whether the edition is abridged.",
                    "example": false
                  }
                }
              },
              "coverPath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                "example": "/player/api/items/li_8f14e45fceea467f/cover"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tags: none.",
                "example": []
              },
              "numTracks": {
                "type": "integer",
                "format": "int64",
                "description": "Tracks in play order.",
                "example": 1,
                "minimum": 0
              },
              "numAudioFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Audio files.",
                "example": 1,
                "minimum": 0
              },
              "numChapters": {
                "type": "integer",
                "format": "int64",
                "description": "Chapters.",
                "example": 0,
                "minimum": 0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds.",
                "example": 36000.0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in its audio files.",
                "example": 100000,
                "minimum": 0
              },
              "audioFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An audio file of a book.",
                  "required": [
                    "index",
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "manuallyVerified",
                    "exclude",
                    "duration",
                    "chapters",
                    "metaTags",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "trackNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number the file's tags state: not read.",
                      "example": 1,
                      "minimum": 0
                    },
                    "discNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number the file's tags state: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "trackNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "discNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "manuallyVerified": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "exclude": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "format": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The container format, such as `mp4` or `mp3`.",
                      "example": "MP4A"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The file's length in seconds.",
                      "example": 36000.0
                    },
                    "bitRate": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Bits per second, if known.",
                      "example": 128000,
                      "minimum": 0
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The file's language, if known.",
                      "example": "en-us"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "timeBase": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The time base, if known.",
                      "example": "1/44100"
                    },
                    "channels": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Audio channels, if known.",
                      "example": 2,
                      "minimum": 0
                    },
                    "channelLayout": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel layout, if known.",
                      "example": "stereo"
                    },
                    "chapters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "Chapters embedded in the file: none are read."
                    },
                    "embeddedCoverArt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "metaTags": {
                      "type": "object",
                      "description": "Tags read from the file: none until the stored media probe reads\nthem."
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The file's media type, such as `audio/mp4`.",
                      "example": "audio/mp4"
                    }
                  }
                },
                "description": "The audio files, when fetched expanded."
              },
              "chapters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "The chapters, when fetched expanded."
              },
              "tracks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A track with its place in the book.",
                  "required": [
                    "index",
                    "startOffset",
                    "duration",
                    "title",
                    "contentUrl",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The track's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "startOffset": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the track starts in the book, in seconds.",
                      "example": 0.0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The track's length in seconds.",
                      "example": 36000.0
                    },
                    "title": {
                      "type": "string",
                      "description": "The track's title: its file name.",
                      "example": "The First"
                    },
                    "contentUrl": {
                      "type": "string",
                      "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The track's media type.",
                      "example": "audio/mp4"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "metadata": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                },
                "description": "The tracks with their place in the book, when fetched expanded."
              }
            }
          },
          "numFiles": {
            "type": "integer",
            "format": "int64",
            "description": "Files in the item.",
            "example": 1,
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes in all its files.",
            "example": 100000,
            "minimum": 0
          },
          "libraryFiles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A file of an item, in the expanded item's `libraryFiles`.",
              "required": [
                "ino",
                "metadata",
                "addedAt",
                "updatedAt",
                "fileType"
              ],
              "properties": {
                "ino": {
                  "type": "string",
                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                  "example": "0"
                },
                "metadata": {
                  "type": "object",
                  "description": "The file's name, size and times.",
                  "required": [
                    "filename",
                    "ext",
                    "path",
                    "relPath",
                    "size",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs"
                  ],
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The file name.",
                      "example": "the-first.m4b"
                    },
                    "ext": {
                      "type": "string",
                      "description": "The extension with its dot (`.m4b`).",
                      "example": ".m4b"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "the-first.m4b"
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's size in bytes.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    }
                  }
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "fileType": {
                  "type": "string",
                  "description": "Always `audio`.",
                  "example": "audio"
                }
              }
            },
            "description": "The item's files, when the item is fetched expanded."
          },
          "userMediaProgress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress, when the app asked for it.",
                "required": [
                  "id",
                  "userId",
                  "libraryItemId",
                  "mediaItemId",
                  "mediaItemType",
                  "duration",
                  "progress",
                  "currentTime",
                  "isFinished",
                  "hideFromContinueListening",
                  "lastUpdate",
                  "startedAt"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The progress id: the item id (one record per patron and item).",
                    "example": "li_8f14e45fceea467f"
                  },
                  "userId": {
                    "type": "string",
                    "description": "The patron's id.",
                    "example": "42"
                  },
                  "libraryItemId": {
                    "type": "string",
                    "description": "The item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "episodeId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "mediaItemId": {
                    "type": "string",
                    "description": "The media id: the item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "mediaItemType": {
                    "type": "string",
                    "description": "Always `book`.",
                    "example": "book"
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds, as last reported.",
                    "example": 36000.0
                  },
                  "progress": {
                    "type": "number",
                    "format": "double",
                    "description": "The share listened, from 0 to 1.",
                    "example": 0.05
                  },
                  "currentTime": {
                    "type": "number",
                    "format": "double",
                    "description": "Where the patron is, in seconds.",
                    "example": 1830.5
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished it.",
                    "example": false
                  },
                  "hideFromContinueListening": {
                    "type": "boolean",
                    "description": "Whether it is hidden from continue listening.",
                    "example": false
                  },
                  "ebookLocation": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "ebookProgress": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "format": "double",
                    "description": "Always null.",
                    "example": null
                  },
                  "lastUpdate": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the progress last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "startedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the patron started, in epoch milliseconds.",
                    "example": 1763620000000
                  },
                  "finishedAt": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "When the patron finished, in epoch milliseconds.",
                    "example": null
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "seriesSequence": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's place in a series, on a series' book list.",
            "example": "1"
          }
        }
      },
      "description": "The items."
    }
  }
}

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `libraryItemIds` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/items/{id}/cover

Serves an item's cover.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Responses

  • 200The cover. Body: binary (image/jpeg)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item, or no cover of it on this node. Body: string (text/plain)
  • 500The library or the cover could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/<id>/cover' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/cover' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/items/<id>/cover",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/cover", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/items/<id>/cover")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The cover. The body is binary (image/jpeg).

Schema:

A image/jpeg body: binary bytes.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item, or no cover of it on this node.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library or the cover could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/items/{id}/play

Opens a play session on an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Request body

The device and what the app asks for; tracks always play directly.

application/json: PlayBody

  • deviceInfoDeviceInfoBody or nullThe device, named in the patron's session list.
  • forceDirectPlayboolean or nullWhether the app asks for direct play; tracks always play directly.
  • forceTranscodeboolean or nullWhether the app asks for transcoding; it gets direct tracks too.
  • mediaPlayerstring or nullThe app's player, shown in the session list.

Responses

  • 200The session, its tracks and where to start. Body: PlaybackSession (application/json)26 fields
    • idstringrequiredThe session id; apps send it back to sync and close.
    • userIdstringrequiredThe patron's id.
    • libraryIdstringrequiredThe library id.
    • libraryItemIdstringrequiredThe item id.
    • bookIdstringrequiredThe media id: the item id.
    • episodeIdstring or nullAlways null.
    • mediaTypestringrequiredAlways [MEDIA_TYPE_BOOK].
    • mediaMetadataBookMetadatarequiredThe book's metadata.
    • chaptersarray of ChapterrequiredThe book's chapters.
    • displayTitlestringrequiredThe title apps show.
    • displayAuthorstringrequiredThe author apps show.
    • coverPathstring or nullA cover path apps test for presence.
    • durationnumber (double)requiredThe book's length in seconds.
    • playMethodinteger (int32)requiredHow the app plays: 0, direct play of the stored files. At least 0.
    • mediaPlayerstringrequiredThe player the app reported.
    • deviceInfoSessionDevicerequiredThe device the session was opened from.
    • serverVersionstringrequired[crate::COMPATIBLE_SERVER_VERSION].
    • datestringrequiredThe day the session started, YYYY-MM-DD in UTC.
    • dayOfWeekstringrequiredThe weekday the session started, in English.
    • timeListeningnumber (double)requiredSeconds listened in this session.
    • startTimenumber (double)requiredWhere the session started, in seconds.
    • currentTimenumber (double)requiredWhere the patron is, in seconds.
    • startedAtinteger (int64)requiredWhen the session started, in epoch milliseconds.
    • updatedAtinteger (int64)requiredWhen it last synced, in epoch milliseconds.
    • audioTracksarray of AudioTrackrequiredThe tracks to play, in order.
    • libraryItemLibraryItem or nullThe item, expanded.
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item, or nothing of it this patron may play here. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be read or written. Body: string (text/plain)
  • 503Storage could not be asked; retry. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/<id>/play' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/play' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/items/<id>/play",
    headers={"Authorization": "Bearer <playerToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/play", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/items/<id>/play")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The session, its tracks and where to start.

{
  "id": "li_8f14e45fceea467f",
  "userId": "42",
  "libraryId": "bookclerk-library",
  "libraryItemId": "li_8f14e45fceea467f",
  "bookId": "li_8f14e45fceea467f",
  "episodeId": null,
  "mediaType": "book",
  "mediaMetadata": {
    "title": "The First",
    "titleIgnorePrefix": "First, The",
    "subtitle": "A Novel",
    "authors": [
      {
        "id": "li_8f14e45fceea467f",
        "name": "Ann Author"
      }
    ],
    "authorName": "Ann Author",
    "authorNameLF": "Author, Ann",
    "narrators": [
      "Nia Narrator"
    ],
    "narratorName": "Nia Narrator",
    "series": [
      {
        "id": "li_8f14e45fceea467f",
        "name": "Ann Author",
        "sequence": "1"
      }
    ],
    "seriesName": "The Saga #1",
    "genres": [
      "Fantasy"
    ],
    "publishedYear": "2024",
    "publishedDate": "2024-03-01",
    "publisher": "Example Press",
    "description": "A short description.",
    "descriptionPlain": "A short description.",
    "isbn": "9780000000002",
    "asin": "B000000000",
    "language": "en-us",
    "explicit": false,
    "abridged": false
  },
  "chapters": [
    {
      "id": 1,
      "start": 0.0,
      "end": 600.0,
      "title": "The First"
    }
  ],
  "displayTitle": "The First",
  "displayAuthor": "Ann Author",
  "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
  "duration": 36000.0,
  "playMethod": 1,
  "mediaPlayer": "Absorb",
  "deviceInfo": {
    "deviceId": "pixel-8",
    "deviceName": "Pixel 8",
    "clientName": "Absorb"
  },
  "serverVersion": "2.17.0",
  "date": "2026-11-20",
  "dayOfWeek": "Friday",
  "timeListening": 60.0,
  "startTime": 1770.5,
  "currentTime": 1830.5,
  "startedAt": 1763620000000,
  "updatedAt": 1763630000000,
  "audioTracks": [
    {
      "index": 1,
      "startOffset": 0.0,
      "duration": 36000.0,
      "title": "The First",
      "contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
      "mimeType": "audio/mp4",
      "codec": "aac",
      "metadata": {
        "filename": "the-first.m4b",
        "ext": ".m4b",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "size": 100000,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000
      }
    }
  ],
  "libraryItem": {
    "id": "li_8f14e45fceea467f",
    "ino": "0",
    "oldLibraryItemId": null,
    "libraryId": "bookclerk-library",
    "folderId": "bookclerk-library",
    "path": "/the-first.m4b",
    "relPath": "the-first.m4b",
    "isFile": true,
    "mtimeMs": 1763600000000,
    "ctimeMs": 1763600000000,
    "birthtimeMs": 1763600000000,
    "addedAt": 1763600000000,
    "updatedAt": 1763630000000,
    "isMissing": false,
    "isInvalid": false,
    "mediaType": "book",
    "media": {
      "id": "li_8f14e45fceea467f",
      "libraryItemId": "li_8f14e45fceea467f",
      "metadata": {
        "title": "The First",
        "titleIgnorePrefix": "First, The",
        "subtitle": "A Novel",
        "authors": [],
        "authorName": "Ann Author",
        "authorNameLF": "Author, Ann",
        "narrators": [
          "Nia Narrator"
        ],
        "narratorName": "Nia Narrator",
        "series": [],
        "seriesName": "The Saga #1",
        "genres": [
          "Fantasy"
        ],
        "publishedYear": "2024",
        "publishedDate": "2024-03-01",
        "publisher": "Example Press",
        "description": "A short description.",
        "descriptionPlain": "A short description.",
        "isbn": "9780000000002",
        "asin": "B000000000",
        "language": "en-us",
        "explicit": false,
        "abridged": false
      },
      "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
      "tags": [],
      "numTracks": 1,
      "numAudioFiles": 1,
      "numChapters": 0,
      "duration": 36000.0,
      "size": 100000,
      "audioFiles": [
        {
          "index": 1,
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "manuallyVerified": false,
          "exclude": false,
          "duration": 36000.0,
          "chapters": [],
          "metaTags": {},
          "mimeType": "audio/mp4"
        }
      ],
      "chapters": [
        {
          "id": 1,
          "start": 0.0,
          "end": 600.0,
          "title": "The First"
        }
      ],
      "tracks": [
        {
          "index": 1,
          "startOffset": 0.0,
          "duration": 36000.0,
          "title": "The First",
          "contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
          "mimeType": "audio/mp4"
        }
      ]
    },
    "numFiles": 1,
    "size": 100000,
    "libraryFiles": [
      {
        "ino": "0",
        "metadata": {
          "filename": "the-first.m4b",
          "ext": ".m4b",
          "path": "/the-first.m4b",
          "relPath": "the-first.m4b",
          "size": 100000,
          "mtimeMs": 1763600000000,
          "ctimeMs": 1763600000000,
          "birthtimeMs": 1763600000000
        },
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "fileType": "audio"
      }
    ],
    "userMediaProgress": {
      "id": "li_8f14e45fceea467f",
      "userId": "42",
      "libraryItemId": "li_8f14e45fceea467f",
      "episodeId": null,
      "mediaItemId": "li_8f14e45fceea467f",
      "mediaItemType": "book",
      "duration": 36000.0,
      "progress": 0.05,
      "currentTime": 1830.5,
      "isFinished": false,
      "hideFromContinueListening": false,
      "ebookLocation": null,
      "ebookProgress": null,
      "lastUpdate": 1763630000000,
      "startedAt": 1763620000000,
      "finishedAt": null
    },
    "seriesSequence": "1"
  }
}

Schema:

{
  "type": "object",
  "description": "A playback session, as `POST /api/items/{id}/play` answers.",
  "required": [
    "id",
    "userId",
    "libraryId",
    "libraryItemId",
    "bookId",
    "mediaType",
    "mediaMetadata",
    "chapters",
    "displayTitle",
    "displayAuthor",
    "duration",
    "playMethod",
    "mediaPlayer",
    "deviceInfo",
    "serverVersion",
    "date",
    "dayOfWeek",
    "timeListening",
    "startTime",
    "currentTime",
    "startedAt",
    "updatedAt",
    "audioTracks"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The session id; apps send it back to sync and close.",
      "example": "li_8f14e45fceea467f"
    },
    "userId": {
      "type": "string",
      "description": "The patron's id.",
      "example": "42"
    },
    "libraryId": {
      "type": "string",
      "description": "The library id.",
      "example": "bookclerk-library"
    },
    "libraryItemId": {
      "type": "string",
      "description": "The item id.",
      "example": "li_8f14e45fceea467f"
    },
    "bookId": {
      "type": "string",
      "description": "The media id: the item id.",
      "example": "li_8f14e45fceea467f"
    },
    "episodeId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": null
    },
    "mediaType": {
      "type": "string",
      "description": "Always [`MEDIA_TYPE_BOOK`].",
      "example": "book"
    },
    "mediaMetadata": {
      "type": "object",
      "description": "The book's metadata.",
      "required": [
        "title",
        "titleIgnorePrefix",
        "authors",
        "authorName",
        "authorNameLF",
        "narrators",
        "narratorName",
        "series",
        "seriesName",
        "genres",
        "explicit",
        "abridged"
      ],
      "properties": {
        "title": {
          "type": "string",
          "description": "The title.",
          "example": "The First"
        },
        "titleIgnorePrefix": {
          "type": "string",
          "description": "The title for sorting.",
          "example": "First, The"
        },
        "subtitle": {
          "type": [
            "string",
            "null"
          ],
          "description": "The subtitle, if any.",
          "example": "A Novel"
        },
        "authors": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "An id and a name.",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The entity's id.",
                "example": "li_8f14e45fceea467f"
              },
              "name": {
                "type": "string",
                "description": "Its display name.",
                "example": "Ann Author"
              }
            }
          },
          "description": "The authors."
        },
        "authorName": {
          "type": "string",
          "description": "The authors' names joined with `, `.",
          "example": "Ann Author"
        },
        "authorNameLF": {
          "type": "string",
          "description": "The authors' names, family name first, joined with `, `.",
          "example": "Author, Ann"
        },
        "narrators": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "The narrators' names.",
          "example": [
            "Nia Narrator"
          ]
        },
        "narratorName": {
          "type": "string",
          "description": "The narrators' names joined with `, `.",
          "example": "Nia Narrator"
        },
        "series": {
          "type": "array",
          "items": {
            "type": "object",
            "description": "A series an item belongs to, with the item's place in it.",
            "required": [
              "id",
              "name"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The series id.",
                "example": "li_8f14e45fceea467f"
              },
              "name": {
                "type": "string",
                "description": "The series name.",
                "example": "Ann Author"
              },
              "sequence": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                "example": "1"
              }
            }
          },
          "description": "The series the book is in."
        },
        "seriesName": {
          "type": "string",
          "description": "The series names with the book's place (`Name #2`), joined.",
          "example": "The Saga #1"
        },
        "genres": {
          "type": "array",
          "items": {
            "type": "string"
          },
          "description": "Genres.",
          "example": [
            "Fantasy"
          ]
        },
        "publishedYear": {
          "type": [
            "string",
            "null"
          ],
          "description": "The year of publication, as a string (`\"2019\"`).",
          "example": "2024"
        },
        "publishedDate": {
          "type": [
            "string",
            "null"
          ],
          "description": "The date of publication, if known.",
          "example": "2024-03-01"
        },
        "publisher": {
          "type": [
            "string",
            "null"
          ],
          "description": "The publisher.",
          "example": "Example Press"
        },
        "description": {
          "type": [
            "string",
            "null"
          ],
          "description": "The description, as the library stores it.",
          "example": "A short description."
        },
        "descriptionPlain": {
          "type": [
            "string",
            "null"
          ],
          "description": "The description with markup removed.",
          "example": "A short description."
        },
        "isbn": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ISBN, if known.",
          "example": "9780000000002"
        },
        "asin": {
          "type": [
            "string",
            "null"
          ],
          "description": "The ASIN, if known.",
          "example": "B000000000"
        },
        "language": {
          "type": [
            "string",
            "null"
          ],
          "description": "The language.",
          "example": "en-us"
        },
        "explicit": {
          "type": "boolean",
          "description": "Always false.",
          "example": false
        },
        "abridged": {
          "type": "boolean",
          "description": "Whether the edition is abridged.",
          "example": false
        }
      }
    },
    "chapters": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A chapter of a book.",
        "required": [
          "id",
          "start",
          "end",
          "title"
        ],
        "properties": {
          "id": {
            "type": "integer",
            "format": "int64",
            "description": "The chapter's place, from 0.",
            "example": 1,
            "minimum": 0
          },
          "start": {
            "type": "number",
            "format": "double",
            "description": "Where it starts, in seconds.",
            "example": 0.0
          },
          "end": {
            "type": "number",
            "format": "double",
            "description": "Where it ends, in seconds.",
            "example": 600.0
          },
          "title": {
            "type": "string",
            "description": "Its title.",
            "example": "The First"
          }
        }
      },
      "description": "The book's chapters."
    },
    "displayTitle": {
      "type": "string",
      "description": "The title apps show.",
      "example": "The First"
    },
    "displayAuthor": {
      "type": "string",
      "description": "The author apps show.",
      "example": "Ann Author"
    },
    "coverPath": {
      "type": [
        "string",
        "null"
      ],
      "description": "A cover path apps test for presence.",
      "example": "/player/api/items/li_8f14e45fceea467f/cover"
    },
    "duration": {
      "type": "number",
      "format": "double",
      "description": "The book's length in seconds.",
      "example": 36000.0
    },
    "playMethod": {
      "type": "integer",
      "format": "int32",
      "description": "How the app plays: 0, direct play of the stored files.",
      "example": 1,
      "minimum": 0
    },
    "mediaPlayer": {
      "type": "string",
      "description": "The player the app reported.",
      "example": "Absorb"
    },
    "deviceInfo": {
      "type": "object",
      "description": "The device the session was opened from.",
      "required": [
        "deviceId"
      ],
      "properties": {
        "deviceId": {
          "type": "string",
          "description": "The device's id: the card's session id.",
          "example": "pixel-8"
        },
        "deviceName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The device name the app reported, if any.",
          "example": "Pixel 8"
        },
        "clientName": {
          "type": [
            "string",
            "null"
          ],
          "description": "The app's name, if reported.",
          "example": "Absorb"
        }
      }
    },
    "serverVersion": {
      "type": "string",
      "description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
      "example": "2.17.0"
    },
    "date": {
      "type": "string",
      "description": "The day the session started, `YYYY-MM-DD` in UTC.",
      "example": "2026-11-20"
    },
    "dayOfWeek": {
      "type": "string",
      "description": "The weekday the session started, in English.",
      "example": "Friday"
    },
    "timeListening": {
      "type": "number",
      "format": "double",
      "description": "Seconds listened in this session.",
      "example": 60.0
    },
    "startTime": {
      "type": "number",
      "format": "double",
      "description": "Where the session started, in seconds.",
      "example": 1770.5
    },
    "currentTime": {
      "type": "number",
      "format": "double",
      "description": "Where the patron is, in seconds.",
      "example": 1830.5
    },
    "startedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the session started, in epoch milliseconds.",
      "example": 1763620000000
    },
    "updatedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When it last synced, in epoch milliseconds.",
      "example": 1763630000000
    },
    "audioTracks": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A track with its place in the book.",
        "required": [
          "index",
          "startOffset",
          "duration",
          "title",
          "contentUrl",
          "mimeType"
        ],
        "properties": {
          "index": {
            "type": "integer",
            "format": "int64",
            "description": "The track's place in play order, from 1.",
            "example": 1,
            "minimum": 0
          },
          "startOffset": {
            "type": "number",
            "format": "double",
            "description": "Where the track starts in the book, in seconds.",
            "example": 0.0
          },
          "duration": {
            "type": "number",
            "format": "double",
            "description": "The track's length in seconds.",
            "example": 36000.0
          },
          "title": {
            "type": "string",
            "description": "The track's title: its file name.",
            "example": "The First"
          },
          "contentUrl": {
            "type": "string",
            "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
            "example": "/player/api/items/li_8f14e45fceea467f/file/0"
          },
          "mimeType": {
            "type": "string",
            "description": "The track's media type.",
            "example": "audio/mp4"
          },
          "codec": {
            "type": [
              "string",
              "null"
            ],
            "description": "The codec, if known.",
            "example": "aac"
          },
          "metadata": {
            "oneOf": [
              {
                "type": "object",
                "description": "The file's name, size and times.",
                "required": [
                  "filename",
                  "ext",
                  "path",
                  "relPath",
                  "size",
                  "mtimeMs",
                  "ctimeMs",
                  "birthtimeMs"
                ],
                "properties": {
                  "filename": {
                    "type": "string",
                    "description": "The file name.",
                    "example": "the-first.m4b"
                  },
                  "ext": {
                    "type": "string",
                    "description": "The extension with its dot (`.m4b`).",
                    "example": ".m4b"
                  },
                  "path": {
                    "type": "string",
                    "description": "A display path: the file name.",
                    "example": "/the-first.m4b"
                  },
                  "relPath": {
                    "type": "string",
                    "description": "A display path: the file name.",
                    "example": "the-first.m4b"
                  },
                  "size": {
                    "type": "integer",
                    "format": "int64",
                    "description": "The file's size in bytes.",
                    "example": 100000,
                    "minimum": 0
                  },
                  "mtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "ctimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "birthtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "description": "The tracks to play, in order."
    },
    "libraryItem": {
      "oneOf": [
        {
          "type": "object",
          "description": "The item, expanded.",
          "required": [
            "id",
            "ino",
            "libraryId",
            "folderId",
            "path",
            "relPath",
            "isFile",
            "mtimeMs",
            "ctimeMs",
            "birthtimeMs",
            "addedAt",
            "updatedAt",
            "isMissing",
            "isInvalid",
            "mediaType",
            "media",
            "numFiles",
            "size"
          ],
          "properties": {
            "id": {
              "type": "string",
              "description": "The item id: the edition id.",
              "example": "li_8f14e45fceea467f"
            },
            "ino": {
              "type": "string",
              "description": "The item's inode as apps expect one: the edition id again.",
              "example": "0"
            },
            "oldLibraryItemId": {
              "type": [
                "string",
                "null"
              ],
              "description": "Always null.",
              "example": null
            },
            "libraryId": {
              "type": "string",
              "description": "The library the item is listed in.",
              "example": "bookclerk-library"
            },
            "folderId": {
              "type": "string",
              "description": "The folder id: the library id.",
              "example": "bookclerk-library"
            },
            "path": {
              "type": "string",
              "description": "A display path: the title.",
              "example": "/the-first.m4b"
            },
            "relPath": {
              "type": "string",
              "description": "A display path: the title.",
              "example": "the-first.m4b"
            },
            "isFile": {
              "type": "boolean",
              "description": "Always false: an item is a folder of tracks.",
              "example": true
            },
            "mtimeMs": {
              "type": "integer",
              "format": "int64",
              "description": "When the copy last changed, in epoch milliseconds.",
              "example": 1763600000000
            },
            "ctimeMs": {
              "type": "integer",
              "format": "int64",
              "description": "When the copy was stored, in epoch milliseconds.",
              "example": 1763600000000
            },
            "birthtimeMs": {
              "type": "integer",
              "format": "int64",
              "description": "When the copy was stored, in epoch milliseconds.",
              "example": 1763600000000
            },
            "addedAt": {
              "type": "integer",
              "format": "int64",
              "description": "When the item joined the library, in epoch milliseconds.",
              "example": 1763600000000
            },
            "updatedAt": {
              "type": "integer",
              "format": "int64",
              "description": "When its record last changed, in epoch milliseconds.",
              "example": 1763630000000
            },
            "isMissing": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "isInvalid": {
              "type": "boolean",
              "description": "Always false.",
              "example": false
            },
            "mediaType": {
              "type": "string",
              "description": "Always [`MEDIA_TYPE_BOOK`].",
              "example": "book"
            },
            "media": {
              "type": "object",
              "description": "The book.",
              "required": [
                "id",
                "metadata",
                "tags",
                "numTracks",
                "numAudioFiles",
                "numChapters",
                "duration",
                "size"
              ],
              "properties": {
                "id": {
                  "type": "string",
                  "description": "The media id: the edition id.",
                  "example": "li_8f14e45fceea467f"
                },
                "libraryItemId": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The item id, when fetched expanded.",
                  "example": "li_8f14e45fceea467f"
                },
                "metadata": {
                  "type": "object",
                  "description": "The book's metadata.",
                  "required": [
                    "title",
                    "titleIgnorePrefix",
                    "authors",
                    "authorName",
                    "authorNameLF",
                    "narrators",
                    "narratorName",
                    "series",
                    "seriesName",
                    "genres",
                    "explicit",
                    "abridged"
                  ],
                  "properties": {
                    "title": {
                      "type": "string",
                      "description": "The title.",
                      "example": "The First"
                    },
                    "titleIgnorePrefix": {
                      "type": "string",
                      "description": "The title for sorting.",
                      "example": "First, The"
                    },
                    "subtitle": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The subtitle, if any.",
                      "example": "A Novel"
                    },
                    "authors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "An id and a name.",
                        "required": [
                          "id",
                          "name"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The entity's id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "name": {
                            "type": "string",
                            "description": "Its display name.",
                            "example": "Ann Author"
                          }
                        }
                      },
                      "description": "The authors."
                    },
                    "authorName": {
                      "type": "string",
                      "description": "The authors' names joined with `, `.",
                      "example": "Ann Author"
                    },
                    "authorNameLF": {
                      "type": "string",
                      "description": "The authors' names, family name first, joined with `, `.",
                      "example": "Author, Ann"
                    },
                    "narrators": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "The narrators' names.",
                      "example": [
                        "Nia Narrator"
                      ]
                    },
                    "narratorName": {
                      "type": "string",
                      "description": "The narrators' names joined with `, `.",
                      "example": "Nia Narrator"
                    },
                    "series": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A series an item belongs to, with the item's place in it.",
                        "required": [
                          "id",
                          "name"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The series id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "name": {
                            "type": "string",
                            "description": "The series name.",
                            "example": "Ann Author"
                          },
                          "sequence": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                            "example": "1"
                          }
                        }
                      },
                      "description": "The series the book is in."
                    },
                    "seriesName": {
                      "type": "string",
                      "description": "The series names with the book's place (`Name #2`), joined.",
                      "example": "The Saga #1"
                    },
                    "genres": {
                      "type": "array",
                      "items": {
                        "type": "string"
                      },
                      "description": "Genres.",
                      "example": [
                        "Fantasy"
                      ]
                    },
                    "publishedYear": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The year of publication, as a string (`\"2019\"`).",
                      "example": "2024"
                    },
                    "publishedDate": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The date of publication, if known.",
                      "example": "2024-03-01"
                    },
                    "publisher": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The publisher.",
                      "example": "Example Press"
                    },
                    "description": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The description, as the library stores it.",
                      "example": "A short description."
                    },
                    "descriptionPlain": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The description with markup removed.",
                      "example": "A short description."
                    },
                    "isbn": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The ISBN, if known.",
                      "example": "9780000000002"
                    },
                    "asin": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The ASIN, if known.",
                      "example": "B000000000"
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The language.",
                      "example": "en-us"
                    },
                    "explicit": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "abridged": {
                      "type": "boolean",
                      "description": "Whether the edition is abridged.",
                      "example": false
                    }
                  }
                },
                "coverPath": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                  "example": "/player/api/items/li_8f14e45fceea467f/cover"
                },
                "tags": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  },
                  "description": "Tags: none.",
                  "example": []
                },
                "numTracks": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Tracks in play order.",
                  "example": 1,
                  "minimum": 0
                },
                "numAudioFiles": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Audio files.",
                  "example": 1,
                  "minimum": 0
                },
                "numChapters": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Chapters.",
                  "example": 0,
                  "minimum": 0
                },
                "duration": {
                  "type": "number",
                  "format": "double",
                  "description": "The book's length in seconds.",
                  "example": 36000.0
                },
                "size": {
                  "type": "integer",
                  "format": "int64",
                  "description": "Bytes in its audio files.",
                  "example": 100000,
                  "minimum": 0
                },
                "audioFiles": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "An audio file of a book.",
                    "required": [
                      "index",
                      "ino",
                      "metadata",
                      "addedAt",
                      "updatedAt",
                      "manuallyVerified",
                      "exclude",
                      "duration",
                      "chapters",
                      "metaTags",
                      "mimeType"
                    ],
                    "properties": {
                      "index": {
                        "type": "integer",
                        "format": "int64",
                        "description": "The file's place in play order, from 1.",
                        "example": 1,
                        "minimum": 0
                      },
                      "ino": {
                        "type": "string",
                        "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                        "example": "0"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The file's name, size and times.",
                        "required": [
                          "filename",
                          "ext",
                          "path",
                          "relPath",
                          "size",
                          "mtimeMs",
                          "ctimeMs",
                          "birthtimeMs"
                        ],
                        "properties": {
                          "filename": {
                            "type": "string",
                            "description": "The file name.",
                            "example": "the-first.m4b"
                          },
                          "ext": {
                            "type": "string",
                            "description": "The extension with its dot (`.m4b`).",
                            "example": ".m4b"
                          },
                          "path": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "/the-first.m4b"
                          },
                          "relPath": {
                            "type": "string",
                            "description": "A display path: the file name.",
                            "example": "the-first.m4b"
                          },
                          "size": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The file's size in bytes.",
                            "example": 100000,
                            "minimum": 0
                          },
                          "mtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "ctimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          },
                          "birthtimeMs": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the file was stored, in epoch milliseconds.",
                            "example": 1763600000000
                          }
                        }
                      },
                      "addedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "updatedAt": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763630000000
                      },
                      "trackNumFromMeta": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "The track number the file's tags state: not read.",
                        "example": 1,
                        "minimum": 0
                      },
                      "discNumFromMeta": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "The disc number the file's tags state: not read.",
                        "example": null,
                        "minimum": 0
                      },
                      "trackNumFromFilename": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "The track number in the file name: not read.",
                        "example": null,
                        "minimum": 0
                      },
                      "discNumFromFilename": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "The disc number in the file name: not read.",
                        "example": null,
                        "minimum": 0
                      },
                      "manuallyVerified": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "exclude": {
                        "type": "boolean",
                        "description": "Always false.",
                        "example": false
                      },
                      "error": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "format": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The container format, such as `mp4` or `mp3`.",
                        "example": "MP4A"
                      },
                      "duration": {
                        "type": "number",
                        "format": "double",
                        "description": "The file's length in seconds.",
                        "example": 36000.0
                      },
                      "bitRate": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "Bits per second, if known.",
                        "example": 128000,
                        "minimum": 0
                      },
                      "language": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The file's language, if known.",
                        "example": "en-us"
                      },
                      "codec": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The codec, if known.",
                        "example": "aac"
                      },
                      "timeBase": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The time base, if known.",
                        "example": "1/44100"
                      },
                      "channels": {
                        "type": [
                          "integer",
                          "null"
                        ],
                        "format": "int64",
                        "description": "Audio channels, if known.",
                        "example": 2,
                        "minimum": 0
                      },
                      "channelLayout": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The channel layout, if known.",
                        "example": "stereo"
                      },
                      "chapters": {
                        "type": "array",
                        "items": {
                          "type": "object",
                          "description": "A chapter of a book.",
                          "required": [
                            "id",
                            "start",
                            "end",
                            "title"
                          ],
                          "properties": {
                            "id": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The chapter's place, from 0.",
                              "example": 1,
                              "minimum": 0
                            },
                            "start": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it starts, in seconds.",
                              "example": 0.0
                            },
                            "end": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it ends, in seconds.",
                              "example": 600.0
                            },
                            "title": {
                              "type": "string",
                              "description": "Its title.",
                              "example": "The First"
                            }
                          }
                        },
                        "description": "Chapters embedded in the file: none are read."
                      },
                      "embeddedCoverArt": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "Always null.",
                        "example": null
                      },
                      "metaTags": {
                        "type": "object",
                        "description": "Tags read from the file: none until the stored media probe reads\nthem."
                      },
                      "mimeType": {
                        "type": "string",
                        "description": "The file's media type, such as `audio/mp4`.",
                        "example": "audio/mp4"
                      }
                    }
                  },
                  "description": "The audio files, when fetched expanded."
                },
                "chapters": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A chapter of a book.",
                    "required": [
                      "id",
                      "start",
                      "end",
                      "title"
                    ],
                    "properties": {
                      "id": {
                        "type": "integer",
                        "format": "int64",
                        "description": "The chapter's place, from 0.",
                        "example": 1,
                        "minimum": 0
                      },
                      "start": {
                        "type": "number",
                        "format": "double",
                        "description": "Where it starts, in seconds.",
                        "example": 0.0
                      },
                      "end": {
                        "type": "number",
                        "format": "double",
                        "description": "Where it ends, in seconds.",
                        "example": 600.0
                      },
                      "title": {
                        "type": "string",
                        "description": "Its title.",
                        "example": "The First"
                      }
                    }
                  },
                  "description": "The chapters, when fetched expanded."
                },
                "tracks": {
                  "type": [
                    "array",
                    "null"
                  ],
                  "items": {
                    "type": "object",
                    "description": "A track with its place in the book.",
                    "required": [
                      "index",
                      "startOffset",
                      "duration",
                      "title",
                      "contentUrl",
                      "mimeType"
                    ],
                    "properties": {
                      "index": {
                        "type": "integer",
                        "format": "int64",
                        "description": "The track's place in play order, from 1.",
                        "example": 1,
                        "minimum": 0
                      },
                      "startOffset": {
                        "type": "number",
                        "format": "double",
                        "description": "Where the track starts in the book, in seconds.",
                        "example": 0.0
                      },
                      "duration": {
                        "type": "number",
                        "format": "double",
                        "description": "The track's length in seconds.",
                        "example": 36000.0
                      },
                      "title": {
                        "type": "string",
                        "description": "The track's title: its file name.",
                        "example": "The First"
                      },
                      "contentUrl": {
                        "type": "string",
                        "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                        "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                      },
                      "mimeType": {
                        "type": "string",
                        "description": "The track's media type.",
                        "example": "audio/mp4"
                      },
                      "codec": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The codec, if known.",
                        "example": "aac"
                      },
                      "metadata": {
                        "oneOf": [
                          {
                            "type": "object",
                            "description": "The file's name, size and times.",
                            "required": [
                              "filename",
                              "ext",
                              "path",
                              "relPath",
                              "size",
                              "mtimeMs",
                              "ctimeMs",
                              "birthtimeMs"
                            ],
                            "properties": {
                              "filename": {
                                "type": "string",
                                "description": "The file name.",
                                "example": "the-first.m4b"
                              },
                              "ext": {
                                "type": "string",
                                "description": "The extension with its dot (`.m4b`).",
                                "example": ".m4b"
                              },
                              "path": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "/the-first.m4b"
                              },
                              "relPath": {
                                "type": "string",
                                "description": "A display path: the file name.",
                                "example": "the-first.m4b"
                              },
                              "size": {
                                "type": "integer",
                                "format": "int64",
                                "description": "The file's size in bytes.",
                                "example": 100000,
                                "minimum": 0
                              },
                              "mtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "ctimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              },
                              "birthtimeMs": {
                                "type": "integer",
                                "format": "int64",
                                "description": "When the file was stored, in epoch milliseconds.",
                                "example": 1763600000000
                              }
                            }
                          },
                          {
                            "type": "null"
                          }
                        ]
                      }
                    }
                  },
                  "description": "The tracks with their place in the book, when fetched expanded."
                }
              }
            },
            "numFiles": {
              "type": "integer",
              "format": "int64",
              "description": "Files in the item.",
              "example": 1,
              "minimum": 0
            },
            "size": {
              "type": "integer",
              "format": "int64",
              "description": "Bytes in all its files.",
              "example": 100000,
              "minimum": 0
            },
            "libraryFiles": {
              "type": [
                "array",
                "null"
              ],
              "items": {
                "type": "object",
                "description": "A file of an item, in the expanded item's `libraryFiles`.",
                "required": [
                  "ino",
                  "metadata",
                  "addedAt",
                  "updatedAt",
                  "fileType"
                ],
                "properties": {
                  "ino": {
                    "type": "string",
                    "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                    "example": "0"
                  },
                  "metadata": {
                    "type": "object",
                    "description": "The file's name, size and times.",
                    "required": [
                      "filename",
                      "ext",
                      "path",
                      "relPath",
                      "size",
                      "mtimeMs",
                      "ctimeMs",
                      "birthtimeMs"
                    ],
                    "properties": {
                      "filename": {
                        "type": "string",
                        "description": "The file name.",
                        "example": "the-first.m4b"
                      },
                      "ext": {
                        "type": "string",
                        "description": "The extension with its dot (`.m4b`).",
                        "example": ".m4b"
                      },
                      "path": {
                        "type": "string",
                        "description": "A display path: the file name.",
                        "example": "/the-first.m4b"
                      },
                      "relPath": {
                        "type": "string",
                        "description": "A display path: the file name.",
                        "example": "the-first.m4b"
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "The file's size in bytes.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "mtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "ctimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      },
                      "birthtimeMs": {
                        "type": "integer",
                        "format": "int64",
                        "description": "When the file was stored, in epoch milliseconds.",
                        "example": 1763600000000
                      }
                    }
                  },
                  "addedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "updatedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the file was stored, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "fileType": {
                    "type": "string",
                    "description": "Always `audio`.",
                    "example": "audio"
                  }
                }
              },
              "description": "The item's files, when the item is fetched expanded."
            },
            "userMediaProgress": {
              "oneOf": [
                {
                  "type": "object",
                  "description": "The patron's progress, when the app asked for it.",
                  "required": [
                    "id",
                    "userId",
                    "libraryItemId",
                    "mediaItemId",
                    "mediaItemType",
                    "duration",
                    "progress",
                    "currentTime",
                    "isFinished",
                    "hideFromContinueListening",
                    "lastUpdate",
                    "startedAt"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The progress id: the item id (one record per patron and item).",
                      "example": "li_8f14e45fceea467f"
                    },
                    "userId": {
                      "type": "string",
                      "description": "The patron's id.",
                      "example": "42"
                    },
                    "libraryItemId": {
                      "type": "string",
                      "description": "The item id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "episodeId": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "mediaItemId": {
                      "type": "string",
                      "description": "The media id: the item id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "mediaItemType": {
                      "type": "string",
                      "description": "Always `book`.",
                      "example": "book"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The book's length in seconds, as last reported.",
                      "example": 36000.0
                    },
                    "progress": {
                      "type": "number",
                      "format": "double",
                      "description": "The share listened, from 0 to 1.",
                      "example": 0.05
                    },
                    "currentTime": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the patron is, in seconds.",
                      "example": 1830.5
                    },
                    "isFinished": {
                      "type": "boolean",
                      "description": "Whether the patron finished it.",
                      "example": false
                    },
                    "hideFromContinueListening": {
                      "type": "boolean",
                      "description": "Whether it is hidden from continue listening.",
                      "example": false
                    },
                    "ebookLocation": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "ebookProgress": {
                      "type": [
                        "number",
                        "null"
                      ],
                      "format": "double",
                      "description": "Always null.",
                      "example": null
                    },
                    "lastUpdate": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the progress last changed, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "startedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the patron started, in epoch milliseconds.",
                      "example": 1763620000000
                    },
                    "finishedAt": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "When the patron finished, in epoch milliseconds.",
                      "example": null
                    }
                  }
                },
                {
                  "type": "null"
                }
              ]
            },
            "seriesSequence": {
              "type": [
                "string",
                "null"
              ],
              "description": "The item's place in a series, on a series' book list.",
              "example": "1"
            }
          }
        },
        {
          "type": "null"
        }
      ]
    }
  }
}

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item, or nothing of it this patron may play here.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: mediaPlayer: invalid type: integer `1`, expected a string at line 1 column 16

Schema:

A text/plain body: a string.

Status 500: The library could not be read or written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: Storage could not be asked; retry.

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/items/{id}/file/{ino}

Streams one audio file of an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.
  • inopathstringrequiredThe file's ino from the item's tracks.
  • Rangeheaderstring or nullOne byte range.

Responses

  • 200The whole file. Body: binary (audio/mp4)
  • 206The requested byte range. Body: binary (audio/mp4)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item or file, or nothing of it this patron may play here. Body: string (text/plain)
  • 416The range starts past the end of the file; Content-Range states the size. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The library could not be read. Body: string (text/plain)
  • 503Storage could not be asked; retry. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/items/<id>/file/<ino>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The whole file. The body is binary (audio/mp4).

Schema:

A audio/mp4 body: binary bytes.

Status 206: The requested byte range. The body is binary (audio/mp4).

Schema:

A audio/mp4 body: binary bytes.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item or file, or nothing of it this patron may play here.

Not Found

Schema:

A text/plain body: a string.

Status 416: The range starts past the end of the file; Content-Range states the size.

{
  "error": "range_not_satisfiable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: Storage could not be asked; retry.

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/items/{id}/file/{ino}/download

Downloads one audio file of an item for offline listening.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.
  • inopathstringrequiredThe file's ino from the item's audio files.
  • Rangeheaderstring or nullOne byte range, to resume.

Responses

  • 200The whole file, as an attachment. Body: binary (audio/mp4)
  • 206The requested byte range. Body: binary (audio/mp4)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron may not save files offline. Body: string (text/plain)
  • 404No such item or file, or nothing of it this patron may play here. Body: string (text/plain)
  • 416The range starts past the end of the file; Content-Range states the size. Body: ErrorMessage (application/json)1 field
    • errorstringrequiredWhat went wrong, as the handler describes it.
  • 500The library could not be read. Body: string (text/plain)
  • 503Storage could not be asked; retry. Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/items/<id>/file/<ino>/download")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The whole file, as an attachment. The body is binary (audio/mp4).

Schema:

A audio/mp4 body: binary bytes.

Status 206: The requested byte range. The body is binary (audio/mp4).

Schema:

A audio/mp4 body: binary bytes.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron may not save files offline.

Downloads are turned off for this patron

Schema:

A text/plain body: a string.

Status 404: No such item or file, or nothing of it this patron may play here.

Not Found

Schema:

A text/plain body: a string.

Status 416: The range starts past the end of the file; Content-Range states the size.

{
  "error": "range_not_satisfiable"
}

Schema:

{
  "type": "object",
  "description": "JSON error object with a single `error` message, written by handlers\nthat report a library or plugin error in their own words.",
  "required": [
    "error"
  ],
  "properties": {
    "error": {
      "type": "string",
      "description": "What went wrong, as the handler describes it.",
      "example": "plugin instance 3f9c2b7e-1d4a-4c8e-9b2f-6a7d8e9f0a1b not found"
    }
  }
}

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: Storage could not be asked; retry.

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/session/{id}/sync

Reports where the patron is in a playing session.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredSession id from the play answer.

Request body

Where the patron is, in seconds.

application/json: SyncBody

  • currentTimenumber (double) or nullThe position, in seconds.
  • timeListenednumber (double) or nullSeconds listened since the last sync.
  • durationnumber (double) or nullThe runtime the app measured, in seconds.

Responses

  • 200OK. Body: string (text/plain)
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such session of the patron's. Body: string (text/plain)
  • 409The session ended; open a new one. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/session/<id>/sync' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/<id>/sync' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/session/<id>/sync",
    headers={"Authorization": "Bearer <playerToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/<id>/sync", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/session/<id>/sync")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such session of the patron's.

Not Found

Schema:

A text/plain body: a string.

Status 409: The session ended; open a new one.

Session ended

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: invalid type: null, expected struct SyncBody at line 1 column 4

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/session/{id}/close

Sends a session's last report, if any, and ends it.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredSession id from the play answer.

Request body

Optionally where the patron is, in seconds; empty keeps the last sync.

application/json: SyncBody

  • currentTimenumber (double) or nullThe position, in seconds.
  • timeListenednumber (double) or nullSeconds listened since the last sync.
  • durationnumber (double) or nullThe runtime the app measured, in seconds.

Responses

  • 200OK; the session is closed. Body: string (text/plain)
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such session of the patron's. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/session/<id>/close' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/<id>/close' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/session/<id>/close",
    headers={"Authorization": "Bearer <playerToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/<id>/close", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/session/<id>/close")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK; the session is closed.

string

Schema:

A text/plain body: a string.

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such session of the patron's.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: invalid type: null, expected struct SyncBody at line 1 column 4

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/session/local

Uploads one session an app played offline.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Request body

An offline session.

application/json: LocalSessionBody

  • idstringrequiredThe app's own id for the session.
  • libraryItemIdstringrequiredThe item.
  • currentTimenumber (double)requiredThe position, in seconds.
  • timeListeningnumber (double) or nullSeconds listened in the session.
  • durationnumber (double) or nullThe runtime the app measured, in seconds.
  • updatedAtinteger (int64) or nullWhen the app last updated the session, in epoch milliseconds.

Responses

  • 200OK. Body: string (text/plain)
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/session/local' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/local' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/session/local",
    headers={"Authorization": "Bearer <playerToken>"},
    json={"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/local", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/session/local")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `id` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/session/local-all

Uploads every session an app played offline.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Request body

Offline sessions, each as POST /player/api/session/local takes one.

application/json: LocalSessionsBody

  • sessionsarray of LocalSessionBodyrequiredThe sessions; each is answered on its own.

Responses

  • 200Each session's outcome. Body: SyncResults (application/json)1 field
    • resultsarray of SyncResultrequiredOne outcome per entry, in the order sent.
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/session/local-all' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/session/local-all' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/session/local-all",
    headers={"Authorization": "Bearer <playerToken>"},
    json={"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/session/local-all", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/session/local-all")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({"sessions": [{"id": "6f9c1d2e-offline", "libraryItemId": "li_8f14e45fceea467f", "currentTime": 754.2}]}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Each session's outcome.

{
  "results": [
    {
      "id": "li_8f14e45fceea467f",
      "success": true,
      "error": null
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`POST /api/session/local-all`.",
  "required": [
    "results"
  ],
  "properties": {
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "One entry's outcome in a batch sync.",
        "required": [
          "id",
          "success"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The session or item id the entry named.",
            "example": "li_8f14e45fceea467f"
          },
          "success": {
            "type": "boolean",
            "description": "Whether it was applied.",
            "example": true
          },
          "error": {
            "type": [
              "string",
              "null"
            ],
            "description": "Why not, when it was not.",
            "example": null
          }
        }
      },
      "description": "One outcome per entry, in the order sent."
    }
  }
}

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `sessions` at line 1 column 2

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/me/progress/{id}

Reads the patron's progress on an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Responses

  • 200The progress. Body: MediaProgress (application/json)16 fields
    • idstringrequiredThe progress id: the item id (one record per patron and item).
    • userIdstringrequiredThe patron's id.
    • libraryItemIdstringrequiredThe item id.
    • episodeIdstring or nullAlways null.
    • mediaItemIdstringrequiredThe media id: the item id.
    • mediaItemTypestringrequiredAlways book.
    • durationnumber (double)requiredThe book's length in seconds, as last reported.
    • progressnumber (double)requiredThe share listened, from 0 to 1.
    • currentTimenumber (double)requiredWhere the patron is, in seconds.
    • isFinishedbooleanrequiredWhether the patron finished it.
    • hideFromContinueListeningbooleanrequiredWhether it is hidden from continue listening.
    • ebookLocationstring or nullAlways null.
    • ebookProgressnumber (double) or nullAlways null.
    • lastUpdateinteger (int64)requiredWhen the progress last changed, in epoch milliseconds.
    • startedAtinteger (int64)requiredWhen the patron started, in epoch milliseconds.
    • finishedAtinteger (int64) or nullWhen the patron finished, in epoch milliseconds.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No progress on that item. Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/me/progress/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/me/progress/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The progress.

{
  "id": "li_8f14e45fceea467f",
  "userId": "42",
  "libraryItemId": "li_8f14e45fceea467f",
  "episodeId": null,
  "mediaItemId": "li_8f14e45fceea467f",
  "mediaItemType": "book",
  "duration": 36000.0,
  "progress": 0.05,
  "currentTime": 1830.5,
  "isFinished": false,
  "hideFromContinueListening": false,
  "ebookLocation": null,
  "ebookProgress": null,
  "lastUpdate": 1763630000000,
  "startedAt": 1763620000000,
  "finishedAt": null
}

Schema:

{
  "type": "object",
  "description": "The patron's progress on one item.",
  "required": [
    "id",
    "userId",
    "libraryItemId",
    "mediaItemId",
    "mediaItemType",
    "duration",
    "progress",
    "currentTime",
    "isFinished",
    "hideFromContinueListening",
    "lastUpdate",
    "startedAt"
  ],
  "properties": {
    "id": {
      "type": "string",
      "description": "The progress id: the item id (one record per patron and item).",
      "example": "li_8f14e45fceea467f"
    },
    "userId": {
      "type": "string",
      "description": "The patron's id.",
      "example": "42"
    },
    "libraryItemId": {
      "type": "string",
      "description": "The item id.",
      "example": "li_8f14e45fceea467f"
    },
    "episodeId": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": null
    },
    "mediaItemId": {
      "type": "string",
      "description": "The media id: the item id.",
      "example": "li_8f14e45fceea467f"
    },
    "mediaItemType": {
      "type": "string",
      "description": "Always `book`.",
      "example": "book"
    },
    "duration": {
      "type": "number",
      "format": "double",
      "description": "The book's length in seconds, as last reported.",
      "example": 36000.0
    },
    "progress": {
      "type": "number",
      "format": "double",
      "description": "The share listened, from 0 to 1.",
      "example": 0.05
    },
    "currentTime": {
      "type": "number",
      "format": "double",
      "description": "Where the patron is, in seconds.",
      "example": 1830.5
    },
    "isFinished": {
      "type": "boolean",
      "description": "Whether the patron finished it.",
      "example": false
    },
    "hideFromContinueListening": {
      "type": "boolean",
      "description": "Whether it is hidden from continue listening.",
      "example": false
    },
    "ebookLocation": {
      "type": [
        "string",
        "null"
      ],
      "description": "Always null.",
      "example": null
    },
    "ebookProgress": {
      "type": [
        "number",
        "null"
      ],
      "format": "double",
      "description": "Always null.",
      "example": null
    },
    "lastUpdate": {
      "type": "integer",
      "format": "int64",
      "description": "When the progress last changed, in epoch milliseconds.",
      "example": 1763630000000
    },
    "startedAt": {
      "type": "integer",
      "format": "int64",
      "description": "When the patron started, in epoch milliseconds.",
      "example": 1763620000000
    },
    "finishedAt": {
      "type": [
        "integer",
        "null"
      ],
      "format": "int64",
      "description": "When the patron finished, in epoch milliseconds.",
      "example": null
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No progress on that item.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

DELETE /player/api/me/progress/{id}

Clears the patron's progress on an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Responses

  • 200OK. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
    -X DELETE \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/player/api/me/progress/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/player/api/me/progress/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

PATCH /player/api/me/progress/{id}

Sets the patron's progress on an item: a seek, Mark finished or Start over.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Request body

The fields to change.

application/json: ProgressBody

  • currentTimenumber (double) or nullThe position, in seconds.
  • progressnumber (double) or nullThe share of duration listened, 0 to 1, read when currentTime is absent.
  • durationnumber (double) or nullThe runtime, in seconds.
  • isFinishedboolean or nullWhether the book is finished.
  • hideFromContinueListeningboolean or nullTrue to take the item off Continue listening.

Responses

  • 200OK. Body: string (text/plain)
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/progress/<id>' \
    -X PATCH \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/<id>' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{}'
import requests

response = requests.patch(
    "http://127.0.0.1:8787/player/api/me/progress/<id>",
    headers={"Authorization": "Bearer <playerToken>"},
    json={},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/<id>", {
  method: "PATCH",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/player/api/me/progress/<id>")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: isFinished: invalid type: integer `1`, expected a boolean at line 1 column 15

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

PATCH /player/api/me/progress/batch/update

Sets the patron's progress on several items.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Request body

One change per item.

application/json: array of ProgressBatchEntry

Responses

  • 200OK. Body: string (text/plain)
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404An item is unknown. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/progress/batch/update' \
    -X PATCH \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '[{"libraryItemId": "li_8f14e45fceea467f"}]'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/progress/batch/update' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '[{"libraryItemId": "li_8f14e45fceea467f"}]'
import requests

response = requests.patch(
    "http://127.0.0.1:8787/player/api/me/progress/batch/update",
    headers={"Authorization": "Bearer <playerToken>"},
    json=[{"libraryItemId": "li_8f14e45fceea467f"}],
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/progress/batch/update", {
  method: "PATCH",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify([{"libraryItemId": "li_8f14e45fceea467f"}]),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/player/api/me/progress/batch/update")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!([{"libraryItemId": "li_8f14e45fceea467f"}]))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: An item is unknown.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: invalid type: null, expected a map at line 1 column 4

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/me/items-in-progress

Lists the items the patron is part way through, most recent first.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Responses

  • 200The items, each with the patron's progress. Body: LibraryItems (application/json)1 field
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/items-in-progress' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/items-in-progress' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/me/items-in-progress",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/items-in-progress", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/me/items-in-progress")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The items, each with the patron's progress.

{
  "libraryItems": [
    {
      "id": "li_8f14e45fceea467f",
      "ino": "0",
      "oldLibraryItemId": null,
      "libraryId": "bookclerk-library",
      "folderId": "bookclerk-library",
      "path": "/the-first.m4b",
      "relPath": "the-first.m4b",
      "isFile": true,
      "mtimeMs": 1763600000000,
      "ctimeMs": 1763600000000,
      "birthtimeMs": 1763600000000,
      "addedAt": 1763600000000,
      "updatedAt": 1763630000000,
      "isMissing": false,
      "isInvalid": false,
      "mediaType": "book",
      "media": {
        "id": "li_8f14e45fceea467f",
        "libraryItemId": "li_8f14e45fceea467f",
        "metadata": {
          "title": "The First",
          "titleIgnorePrefix": "First, The",
          "authors": [],
          "authorName": "Ann Author",
          "authorNameLF": "Author, Ann",
          "narrators": [
            "Nia Narrator"
          ],
          "narratorName": "Nia Narrator",
          "series": [],
          "seriesName": "The Saga #1",
          "genres": [
            "Fantasy"
          ],
          "explicit": false,
          "abridged": false
        },
        "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
        "tags": [],
        "numTracks": 1,
        "numAudioFiles": 1,
        "numChapters": 0,
        "duration": 36000.0,
        "size": 100000,
        "audioFiles": [],
        "chapters": [],
        "tracks": []
      },
      "numFiles": 1,
      "size": 100000,
      "libraryFiles": [
        {
          "ino": "0",
          "metadata": {
            "filename": "the-first.m4b",
            "ext": ".m4b",
            "path": "/the-first.m4b",
            "relPath": "the-first.m4b",
            "size": 100000,
            "mtimeMs": 1763600000000,
            "ctimeMs": 1763600000000,
            "birthtimeMs": 1763600000000
          },
          "addedAt": 1763600000000,
          "updatedAt": 1763630000000,
          "fileType": "audio"
        }
      ],
      "userMediaProgress": {
        "id": "li_8f14e45fceea467f",
        "userId": "42",
        "libraryItemId": "li_8f14e45fceea467f",
        "episodeId": null,
        "mediaItemId": "li_8f14e45fceea467f",
        "mediaItemType": "book",
        "duration": 36000.0,
        "progress": 0.05,
        "currentTime": 1830.5,
        "isFinished": false,
        "hideFromContinueListening": false,
        "ebookLocation": null,
        "ebookProgress": null,
        "lastUpdate": 1763630000000,
        "startedAt": 1763620000000,
        "finishedAt": null
      },
      "seriesSequence": "1"
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`{ \"libraryItems\": [...] }`: in-progress items and batch reads.",
  "required": [
    "libraryItems"
  ],
  "properties": {
    "libraryItems": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "An item: an edition with a stored copy.",
        "required": [
          "id",
          "ino",
          "libraryId",
          "folderId",
          "path",
          "relPath",
          "isFile",
          "mtimeMs",
          "ctimeMs",
          "birthtimeMs",
          "addedAt",
          "updatedAt",
          "isMissing",
          "isInvalid",
          "mediaType",
          "media",
          "numFiles",
          "size"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id: the edition id.",
            "example": "li_8f14e45fceea467f"
          },
          "ino": {
            "type": "string",
            "description": "The item's inode as apps expect one: the edition id again.",
            "example": "0"
          },
          "oldLibraryItemId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "libraryId": {
            "type": "string",
            "description": "The library the item is listed in.",
            "example": "bookclerk-library"
          },
          "folderId": {
            "type": "string",
            "description": "The folder id: the library id.",
            "example": "bookclerk-library"
          },
          "path": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "/the-first.m4b"
          },
          "relPath": {
            "type": "string",
            "description": "A display path: the title.",
            "example": "the-first.m4b"
          },
          "isFile": {
            "type": "boolean",
            "description": "Always false: an item is a folder of tracks.",
            "example": true
          },
          "mtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy last changed, in epoch milliseconds.",
            "example": 1763600000000
          },
          "ctimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "birthtimeMs": {
            "type": "integer",
            "format": "int64",
            "description": "When the copy was stored, in epoch milliseconds.",
            "example": 1763600000000
          },
          "addedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the item joined the library, in epoch milliseconds.",
            "example": 1763600000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When its record last changed, in epoch milliseconds.",
            "example": 1763630000000
          },
          "isMissing": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "isInvalid": {
            "type": "boolean",
            "description": "Always false.",
            "example": false
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "media": {
            "type": "object",
            "description": "The book.",
            "required": [
              "id",
              "metadata",
              "tags",
              "numTracks",
              "numAudioFiles",
              "numChapters",
              "duration",
              "size"
            ],
            "properties": {
              "id": {
                "type": "string",
                "description": "The media id: the edition id.",
                "example": "li_8f14e45fceea467f"
              },
              "libraryItemId": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The item id, when fetched expanded.",
                "example": "li_8f14e45fceea467f"
              },
              "metadata": {
                "type": "object",
                "description": "The book's metadata.",
                "required": [
                  "title",
                  "titleIgnorePrefix",
                  "authors",
                  "authorName",
                  "authorNameLF",
                  "narrators",
                  "narratorName",
                  "series",
                  "seriesName",
                  "genres",
                  "explicit",
                  "abridged"
                ],
                "properties": {
                  "title": {
                    "type": "string",
                    "description": "The title.",
                    "example": "The First"
                  },
                  "titleIgnorePrefix": {
                    "type": "string",
                    "description": "The title for sorting.",
                    "example": "First, The"
                  },
                  "subtitle": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The subtitle, if any.",
                    "example": "A Novel"
                  },
                  "authors": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "An id and a name.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The entity's id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "Its display name.",
                          "example": "Ann Author"
                        }
                      }
                    },
                    "description": "The authors."
                  },
                  "authorName": {
                    "type": "string",
                    "description": "The authors' names joined with `, `.",
                    "example": "Ann Author"
                  },
                  "authorNameLF": {
                    "type": "string",
                    "description": "The authors' names, family name first, joined with `, `.",
                    "example": "Author, Ann"
                  },
                  "narrators": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "The narrators' names.",
                    "example": [
                      "Nia Narrator"
                    ]
                  },
                  "narratorName": {
                    "type": "string",
                    "description": "The narrators' names joined with `, `.",
                    "example": "Nia Narrator"
                  },
                  "series": {
                    "type": "array",
                    "items": {
                      "type": "object",
                      "description": "A series an item belongs to, with the item's place in it.",
                      "required": [
                        "id",
                        "name"
                      ],
                      "properties": {
                        "id": {
                          "type": "string",
                          "description": "The series id.",
                          "example": "li_8f14e45fceea467f"
                        },
                        "name": {
                          "type": "string",
                          "description": "The series name.",
                          "example": "Ann Author"
                        },
                        "sequence": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                          "example": "1"
                        }
                      }
                    },
                    "description": "The series the book is in."
                  },
                  "seriesName": {
                    "type": "string",
                    "description": "The series names with the book's place (`Name #2`), joined.",
                    "example": "The Saga #1"
                  },
                  "genres": {
                    "type": "array",
                    "items": {
                      "type": "string"
                    },
                    "description": "Genres.",
                    "example": [
                      "Fantasy"
                    ]
                  },
                  "publishedYear": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The year of publication, as a string (`\"2019\"`).",
                    "example": "2024"
                  },
                  "publishedDate": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The date of publication, if known.",
                    "example": "2024-03-01"
                  },
                  "publisher": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The publisher.",
                    "example": "Example Press"
                  },
                  "description": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description, as the library stores it.",
                    "example": "A short description."
                  },
                  "descriptionPlain": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The description with markup removed.",
                    "example": "A short description."
                  },
                  "isbn": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ISBN, if known.",
                    "example": "9780000000002"
                  },
                  "asin": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The ASIN, if known.",
                    "example": "B000000000"
                  },
                  "language": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The language.",
                    "example": "en-us"
                  },
                  "explicit": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "abridged": {
                    "type": "boolean",
                    "description": "Whether the edition is abridged.",
                    "example": false
                  }
                }
              },
              "coverPath": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                "example": "/player/api/items/li_8f14e45fceea467f/cover"
              },
              "tags": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Tags: none.",
                "example": []
              },
              "numTracks": {
                "type": "integer",
                "format": "int64",
                "description": "Tracks in play order.",
                "example": 1,
                "minimum": 0
              },
              "numAudioFiles": {
                "type": "integer",
                "format": "int64",
                "description": "Audio files.",
                "example": 1,
                "minimum": 0
              },
              "numChapters": {
                "type": "integer",
                "format": "int64",
                "description": "Chapters.",
                "example": 0,
                "minimum": 0
              },
              "duration": {
                "type": "number",
                "format": "double",
                "description": "The book's length in seconds.",
                "example": 36000.0
              },
              "size": {
                "type": "integer",
                "format": "int64",
                "description": "Bytes in its audio files.",
                "example": 100000,
                "minimum": 0
              },
              "audioFiles": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "An audio file of a book.",
                  "required": [
                    "index",
                    "ino",
                    "metadata",
                    "addedAt",
                    "updatedAt",
                    "manuallyVerified",
                    "exclude",
                    "duration",
                    "chapters",
                    "metaTags",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "ino": {
                      "type": "string",
                      "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                      "example": "0"
                    },
                    "metadata": {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    "addedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "updatedAt": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763630000000
                    },
                    "trackNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number the file's tags state: not read.",
                      "example": 1,
                      "minimum": 0
                    },
                    "discNumFromMeta": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number the file's tags state: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "trackNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The track number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "discNumFromFilename": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "The disc number in the file name: not read.",
                      "example": null,
                      "minimum": 0
                    },
                    "manuallyVerified": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "exclude": {
                      "type": "boolean",
                      "description": "Always false.",
                      "example": false
                    },
                    "error": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "format": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The container format, such as `mp4` or `mp3`.",
                      "example": "MP4A"
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The file's length in seconds.",
                      "example": 36000.0
                    },
                    "bitRate": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Bits per second, if known.",
                      "example": 128000,
                      "minimum": 0
                    },
                    "language": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The file's language, if known.",
                      "example": "en-us"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "timeBase": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The time base, if known.",
                      "example": "1/44100"
                    },
                    "channels": {
                      "type": [
                        "integer",
                        "null"
                      ],
                      "format": "int64",
                      "description": "Audio channels, if known.",
                      "example": 2,
                      "minimum": 0
                    },
                    "channelLayout": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The channel layout, if known.",
                      "example": "stereo"
                    },
                    "chapters": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "description": "A chapter of a book.",
                        "required": [
                          "id",
                          "start",
                          "end",
                          "title"
                        ],
                        "properties": {
                          "id": {
                            "type": "integer",
                            "format": "int64",
                            "description": "The chapter's place, from 0.",
                            "example": 1,
                            "minimum": 0
                          },
                          "start": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it starts, in seconds.",
                            "example": 0.0
                          },
                          "end": {
                            "type": "number",
                            "format": "double",
                            "description": "Where it ends, in seconds.",
                            "example": 600.0
                          },
                          "title": {
                            "type": "string",
                            "description": "Its title.",
                            "example": "The First"
                          }
                        }
                      },
                      "description": "Chapters embedded in the file: none are read."
                    },
                    "embeddedCoverArt": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "Always null.",
                      "example": null
                    },
                    "metaTags": {
                      "type": "object",
                      "description": "Tags read from the file: none until the stored media probe reads\nthem."
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The file's media type, such as `audio/mp4`.",
                      "example": "audio/mp4"
                    }
                  }
                },
                "description": "The audio files, when fetched expanded."
              },
              "chapters": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A chapter of a book.",
                  "required": [
                    "id",
                    "start",
                    "end",
                    "title"
                  ],
                  "properties": {
                    "id": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The chapter's place, from 0.",
                      "example": 1,
                      "minimum": 0
                    },
                    "start": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it starts, in seconds.",
                      "example": 0.0
                    },
                    "end": {
                      "type": "number",
                      "format": "double",
                      "description": "Where it ends, in seconds.",
                      "example": 600.0
                    },
                    "title": {
                      "type": "string",
                      "description": "Its title.",
                      "example": "The First"
                    }
                  }
                },
                "description": "The chapters, when fetched expanded."
              },
              "tracks": {
                "type": [
                  "array",
                  "null"
                ],
                "items": {
                  "type": "object",
                  "description": "A track with its place in the book.",
                  "required": [
                    "index",
                    "startOffset",
                    "duration",
                    "title",
                    "contentUrl",
                    "mimeType"
                  ],
                  "properties": {
                    "index": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The track's place in play order, from 1.",
                      "example": 1,
                      "minimum": 0
                    },
                    "startOffset": {
                      "type": "number",
                      "format": "double",
                      "description": "Where the track starts in the book, in seconds.",
                      "example": 0.0
                    },
                    "duration": {
                      "type": "number",
                      "format": "double",
                      "description": "The track's length in seconds.",
                      "example": 36000.0
                    },
                    "title": {
                      "type": "string",
                      "description": "The track's title: its file name.",
                      "example": "The First"
                    },
                    "contentUrl": {
                      "type": "string",
                      "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                      "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                    },
                    "mimeType": {
                      "type": "string",
                      "description": "The track's media type.",
                      "example": "audio/mp4"
                    },
                    "codec": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The codec, if known.",
                      "example": "aac"
                    },
                    "metadata": {
                      "oneOf": [
                        {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        {
                          "type": "null"
                        }
                      ]
                    }
                  }
                },
                "description": "The tracks with their place in the book, when fetched expanded."
              }
            }
          },
          "numFiles": {
            "type": "integer",
            "format": "int64",
            "description": "Files in the item.",
            "example": 1,
            "minimum": 0
          },
          "size": {
            "type": "integer",
            "format": "int64",
            "description": "Bytes in all its files.",
            "example": 100000,
            "minimum": 0
          },
          "libraryFiles": {
            "type": [
              "array",
              "null"
            ],
            "items": {
              "type": "object",
              "description": "A file of an item, in the expanded item's `libraryFiles`.",
              "required": [
                "ino",
                "metadata",
                "addedAt",
                "updatedAt",
                "fileType"
              ],
              "properties": {
                "ino": {
                  "type": "string",
                  "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                  "example": "0"
                },
                "metadata": {
                  "type": "object",
                  "description": "The file's name, size and times.",
                  "required": [
                    "filename",
                    "ext",
                    "path",
                    "relPath",
                    "size",
                    "mtimeMs",
                    "ctimeMs",
                    "birthtimeMs"
                  ],
                  "properties": {
                    "filename": {
                      "type": "string",
                      "description": "The file name.",
                      "example": "the-first.m4b"
                    },
                    "ext": {
                      "type": "string",
                      "description": "The extension with its dot (`.m4b`).",
                      "example": ".m4b"
                    },
                    "path": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "/the-first.m4b"
                    },
                    "relPath": {
                      "type": "string",
                      "description": "A display path: the file name.",
                      "example": "the-first.m4b"
                    },
                    "size": {
                      "type": "integer",
                      "format": "int64",
                      "description": "The file's size in bytes.",
                      "example": 100000,
                      "minimum": 0
                    },
                    "mtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "ctimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    },
                    "birthtimeMs": {
                      "type": "integer",
                      "format": "int64",
                      "description": "When the file was stored, in epoch milliseconds.",
                      "example": 1763600000000
                    }
                  }
                },
                "addedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763600000000
                },
                "updatedAt": {
                  "type": "integer",
                  "format": "int64",
                  "description": "When the file was stored, in epoch milliseconds.",
                  "example": 1763630000000
                },
                "fileType": {
                  "type": "string",
                  "description": "Always `audio`.",
                  "example": "audio"
                }
              }
            },
            "description": "The item's files, when the item is fetched expanded."
          },
          "userMediaProgress": {
            "oneOf": [
              {
                "type": "object",
                "description": "The patron's progress, when the app asked for it.",
                "required": [
                  "id",
                  "userId",
                  "libraryItemId",
                  "mediaItemId",
                  "mediaItemType",
                  "duration",
                  "progress",
                  "currentTime",
                  "isFinished",
                  "hideFromContinueListening",
                  "lastUpdate",
                  "startedAt"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The progress id: the item id (one record per patron and item).",
                    "example": "li_8f14e45fceea467f"
                  },
                  "userId": {
                    "type": "string",
                    "description": "The patron's id.",
                    "example": "42"
                  },
                  "libraryItemId": {
                    "type": "string",
                    "description": "The item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "episodeId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "mediaItemId": {
                    "type": "string",
                    "description": "The media id: the item id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "mediaItemType": {
                    "type": "string",
                    "description": "Always `book`.",
                    "example": "book"
                  },
                  "duration": {
                    "type": "number",
                    "format": "double",
                    "description": "The book's length in seconds, as last reported.",
                    "example": 36000.0
                  },
                  "progress": {
                    "type": "number",
                    "format": "double",
                    "description": "The share listened, from 0 to 1.",
                    "example": 0.05
                  },
                  "currentTime": {
                    "type": "number",
                    "format": "double",
                    "description": "Where the patron is, in seconds.",
                    "example": 1830.5
                  },
                  "isFinished": {
                    "type": "boolean",
                    "description": "Whether the patron finished it.",
                    "example": false
                  },
                  "hideFromContinueListening": {
                    "type": "boolean",
                    "description": "Whether it is hidden from continue listening.",
                    "example": false
                  },
                  "ebookLocation": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "ebookProgress": {
                    "type": [
                      "number",
                      "null"
                    ],
                    "format": "double",
                    "description": "Always null.",
                    "example": null
                  },
                  "lastUpdate": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the progress last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "startedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the patron started, in epoch milliseconds.",
                    "example": 1763620000000
                  },
                  "finishedAt": {
                    "type": [
                      "integer",
                      "null"
                    ],
                    "format": "int64",
                    "description": "When the patron finished, in epoch milliseconds.",
                    "example": null
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          },
          "seriesSequence": {
            "type": [
              "string",
              "null"
            ],
            "description": "The item's place in a series, on a series' book list.",
            "example": "1"
          }
        }
      },
      "description": "The items."
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/me/listening-sessions

Lists the patron's play sessions, newest first.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • itemsPerPagequeryinteger (int64)Sessions per page, default 10.
  • pagequeryinteger (int64)Page number, from 0.

Responses

  • 200A page of sessions. Body: SessionPage (application/json)5 fields
    • totalinteger (int64)requiredSessions in all. At least 0.
    • numPagesinteger (int64)requiredPages in all. At least 0.
    • pageinteger (int64)requiredThe page number, from 0. At least 0.
    • itemsPerPageinteger (int64)requiredSessions per page. At least 0.
    • sessionsarray of PlaybackSessionrequiredThe page's sessions, newest first.
  • 400A query value is out of range. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/listening-sessions' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/listening-sessions' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/me/listening-sessions",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/listening-sessions", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/me/listening-sessions")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: A page of sessions.

{
  "total": 1,
  "numPages": 1,
  "page": 0,
  "itemsPerPage": 20,
  "sessions": [
    {
      "id": "li_8f14e45fceea467f",
      "userId": "42",
      "libraryId": "bookclerk-library",
      "libraryItemId": "li_8f14e45fceea467f",
      "bookId": "li_8f14e45fceea467f",
      "episodeId": null,
      "mediaType": "book",
      "mediaMetadata": {
        "title": "The First",
        "titleIgnorePrefix": "First, The",
        "subtitle": "A Novel",
        "authors": [],
        "authorName": "Ann Author",
        "authorNameLF": "Author, Ann",
        "narrators": [
          "Nia Narrator"
        ],
        "narratorName": "Nia Narrator",
        "series": [],
        "seriesName": "The Saga #1",
        "genres": [
          "Fantasy"
        ],
        "publishedYear": "2024",
        "publishedDate": "2024-03-01",
        "publisher": "Example Press",
        "description": "A short description.",
        "descriptionPlain": "A short description.",
        "isbn": "9780000000002",
        "asin": "B000000000",
        "language": "en-us",
        "explicit": false,
        "abridged": false
      },
      "chapters": [
        {
          "id": 1,
          "start": 0.0,
          "end": 600.0,
          "title": "The First"
        }
      ],
      "displayTitle": "The First",
      "displayAuthor": "Ann Author",
      "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
      "duration": 36000.0,
      "playMethod": 1,
      "mediaPlayer": "Absorb",
      "deviceInfo": {
        "deviceId": "pixel-8",
        "deviceName": "Pixel 8",
        "clientName": "Absorb"
      },
      "serverVersion": "2.17.0",
      "date": "2026-11-20",
      "dayOfWeek": "Friday",
      "timeListening": 60.0,
      "startTime": 1770.5,
      "currentTime": 1830.5,
      "startedAt": 1763620000000,
      "updatedAt": 1763630000000,
      "audioTracks": [
        {
          "index": 1,
          "startOffset": 0.0,
          "duration": 36000.0,
          "title": "The First",
          "contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
          "mimeType": "audio/mp4"
        }
      ],
      "libraryItem": {
        "id": "li_8f14e45fceea467f",
        "ino": "0",
        "oldLibraryItemId": null,
        "libraryId": "bookclerk-library",
        "folderId": "bookclerk-library",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "isFile": true,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000,
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "id": "li_8f14e45fceea467f",
          "metadata": {
            "title": "The First",
            "titleIgnorePrefix": "First, The",
            "authors": [],
            "authorName": "Ann Author",
            "authorNameLF": "Author, Ann",
            "narrators": [
              "Nia Narrator"
            ],
            "narratorName": "Nia Narrator",
            "series": [],
            "seriesName": "The Saga #1",
            "genres": [
              "Fantasy"
            ],
            "explicit": false,
            "abridged": false
          },
          "tags": [],
          "numTracks": 1,
          "numAudioFiles": 1,
          "numChapters": 0,
          "duration": 36000.0,
          "size": 100000
        },
        "numFiles": 1,
        "size": 100000,
        "libraryFiles": [],
        "userMediaProgress": {
          "id": "li_8f14e45fceea467f",
          "userId": "42",
          "libraryItemId": "li_8f14e45fceea467f",
          "mediaItemId": "li_8f14e45fceea467f",
          "mediaItemType": "book",
          "duration": 36000.0,
          "progress": 0.05,
          "currentTime": 1830.5,
          "isFinished": false,
          "hideFromContinueListening": false,
          "lastUpdate": 1763630000000,
          "startedAt": 1763620000000
        },
        "seriesSequence": "1"
      }
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/me/listening-sessions`.",
  "required": [
    "total",
    "numPages",
    "page",
    "itemsPerPage",
    "sessions"
  ],
  "properties": {
    "total": {
      "type": "integer",
      "format": "int64",
      "description": "Sessions in all.",
      "example": 1,
      "minimum": 0
    },
    "numPages": {
      "type": "integer",
      "format": "int64",
      "description": "Pages in all.",
      "example": 1,
      "minimum": 0
    },
    "page": {
      "type": "integer",
      "format": "int64",
      "description": "The page number, from 0.",
      "example": 0,
      "minimum": 0
    },
    "itemsPerPage": {
      "type": "integer",
      "format": "int64",
      "description": "Sessions per page.",
      "example": 20,
      "minimum": 0
    },
    "sessions": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A playback session, as `POST /api/items/{id}/play` answers.",
        "required": [
          "id",
          "userId",
          "libraryId",
          "libraryItemId",
          "bookId",
          "mediaType",
          "mediaMetadata",
          "chapters",
          "displayTitle",
          "displayAuthor",
          "duration",
          "playMethod",
          "mediaPlayer",
          "deviceInfo",
          "serverVersion",
          "date",
          "dayOfWeek",
          "timeListening",
          "startTime",
          "currentTime",
          "startedAt",
          "updatedAt",
          "audioTracks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The session id; apps send it back to sync and close.",
            "example": "li_8f14e45fceea467f"
          },
          "userId": {
            "type": "string",
            "description": "The patron's id.",
            "example": "42"
          },
          "libraryId": {
            "type": "string",
            "description": "The library id.",
            "example": "bookclerk-library"
          },
          "libraryItemId": {
            "type": "string",
            "description": "The item id.",
            "example": "li_8f14e45fceea467f"
          },
          "bookId": {
            "type": "string",
            "description": "The media id: the item id.",
            "example": "li_8f14e45fceea467f"
          },
          "episodeId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "mediaMetadata": {
            "type": "object",
            "description": "The book's metadata.",
            "required": [
              "title",
              "titleIgnorePrefix",
              "authors",
              "authorName",
              "authorNameLF",
              "narrators",
              "narratorName",
              "series",
              "seriesName",
              "genres",
              "explicit",
              "abridged"
            ],
            "properties": {
              "title": {
                "type": "string",
                "description": "The title.",
                "example": "The First"
              },
              "titleIgnorePrefix": {
                "type": "string",
                "description": "The title for sorting.",
                "example": "First, The"
              },
              "subtitle": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The subtitle, if any.",
                "example": "A Novel"
              },
              "authors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "An id and a name.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The entity's id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "Its display name.",
                      "example": "Ann Author"
                    }
                  }
                },
                "description": "The authors."
              },
              "authorName": {
                "type": "string",
                "description": "The authors' names joined with `, `.",
                "example": "Ann Author"
              },
              "authorNameLF": {
                "type": "string",
                "description": "The authors' names, family name first, joined with `, `.",
                "example": "Author, Ann"
              },
              "narrators": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The narrators' names.",
                "example": [
                  "Nia Narrator"
                ]
              },
              "narratorName": {
                "type": "string",
                "description": "The narrators' names joined with `, `.",
                "example": "Nia Narrator"
              },
              "series": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A series an item belongs to, with the item's place in it.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The series id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "The series name.",
                      "example": "Ann Author"
                    },
                    "sequence": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                      "example": "1"
                    }
                  }
                },
                "description": "The series the book is in."
              },
              "seriesName": {
                "type": "string",
                "description": "The series names with the book's place (`Name #2`), joined.",
                "example": "The Saga #1"
              },
              "genres": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Genres.",
                "example": [
                  "Fantasy"
                ]
              },
              "publishedYear": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The year of publication, as a string (`\"2019\"`).",
                "example": "2024"
              },
              "publishedDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The date of publication, if known.",
                "example": "2024-03-01"
              },
              "publisher": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The publisher.",
                "example": "Example Press"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description, as the library stores it.",
                "example": "A short description."
              },
              "descriptionPlain": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description with markup removed.",
                "example": "A short description."
              },
              "isbn": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ISBN, if known.",
                "example": "9780000000002"
              },
              "asin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ASIN, if known.",
                "example": "B000000000"
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The language.",
                "example": "en-us"
              },
              "explicit": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "abridged": {
                "type": "boolean",
                "description": "Whether the edition is abridged.",
                "example": false
              }
            }
          },
          "chapters": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A chapter of a book.",
              "required": [
                "id",
                "start",
                "end",
                "title"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The chapter's place, from 0.",
                  "example": 1,
                  "minimum": 0
                },
                "start": {
                  "type": "number",
                  "format": "double",
                  "description": "Where it starts, in seconds.",
                  "example": 0.0
                },
                "end": {
                  "type": "number",
                  "format": "double",
                  "description": "Where it ends, in seconds.",
                  "example": 600.0
                },
                "title": {
                  "type": "string",
                  "description": "Its title.",
                  "example": "The First"
                }
              }
            },
            "description": "The book's chapters."
          },
          "displayTitle": {
            "type": "string",
            "description": "The title apps show.",
            "example": "The First"
          },
          "displayAuthor": {
            "type": "string",
            "description": "The author apps show.",
            "example": "Ann Author"
          },
          "coverPath": {
            "type": [
              "string",
              "null"
            ],
            "description": "A cover path apps test for presence.",
            "example": "/player/api/items/li_8f14e45fceea467f/cover"
          },
          "duration": {
            "type": "number",
            "format": "double",
            "description": "The book's length in seconds.",
            "example": 36000.0
          },
          "playMethod": {
            "type": "integer",
            "format": "int32",
            "description": "How the app plays: 0, direct play of the stored files.",
            "example": 1,
            "minimum": 0
          },
          "mediaPlayer": {
            "type": "string",
            "description": "The player the app reported.",
            "example": "Absorb"
          },
          "deviceInfo": {
            "type": "object",
            "description": "The device the session was opened from.",
            "required": [
              "deviceId"
            ],
            "properties": {
              "deviceId": {
                "type": "string",
                "description": "The device's id: the card's session id.",
                "example": "pixel-8"
              },
              "deviceName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The device name the app reported, if any.",
                "example": "Pixel 8"
              },
              "clientName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The app's name, if reported.",
                "example": "Absorb"
              }
            }
          },
          "serverVersion": {
            "type": "string",
            "description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
            "example": "2.17.0"
          },
          "date": {
            "type": "string",
            "description": "The day the session started, `YYYY-MM-DD` in UTC.",
            "example": "2026-11-20"
          },
          "dayOfWeek": {
            "type": "string",
            "description": "The weekday the session started, in English.",
            "example": "Friday"
          },
          "timeListening": {
            "type": "number",
            "format": "double",
            "description": "Seconds listened in this session.",
            "example": 60.0
          },
          "startTime": {
            "type": "number",
            "format": "double",
            "description": "Where the session started, in seconds.",
            "example": 1770.5
          },
          "currentTime": {
            "type": "number",
            "format": "double",
            "description": "Where the patron is, in seconds.",
            "example": 1830.5
          },
          "startedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the session started, in epoch milliseconds.",
            "example": 1763620000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When it last synced, in epoch milliseconds.",
            "example": 1763630000000
          },
          "audioTracks": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A track with its place in the book.",
              "required": [
                "index",
                "startOffset",
                "duration",
                "title",
                "contentUrl",
                "mimeType"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The track's place in play order, from 1.",
                  "example": 1,
                  "minimum": 0
                },
                "startOffset": {
                  "type": "number",
                  "format": "double",
                  "description": "Where the track starts in the book, in seconds.",
                  "example": 0.0
                },
                "duration": {
                  "type": "number",
                  "format": "double",
                  "description": "The track's length in seconds.",
                  "example": 36000.0
                },
                "title": {
                  "type": "string",
                  "description": "The track's title: its file name.",
                  "example": "The First"
                },
                "contentUrl": {
                  "type": "string",
                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                },
                "mimeType": {
                  "type": "string",
                  "description": "The track's media type.",
                  "example": "audio/mp4"
                },
                "codec": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The codec, if known.",
                  "example": "aac"
                },
                "metadata": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "The tracks to play, in order."
          },
          "libraryItem": {
            "oneOf": [
              {
                "type": "object",
                "description": "The item, expanded.",
                "required": [
                  "id",
                  "ino",
                  "libraryId",
                  "folderId",
                  "path",
                  "relPath",
                  "isFile",
                  "mtimeMs",
                  "ctimeMs",
                  "birthtimeMs",
                  "addedAt",
                  "updatedAt",
                  "isMissing",
                  "isInvalid",
                  "mediaType",
                  "media",
                  "numFiles",
                  "size"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The item id: the edition id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "ino": {
                    "type": "string",
                    "description": "The item's inode as apps expect one: the edition id again.",
                    "example": "0"
                  },
                  "oldLibraryItemId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "libraryId": {
                    "type": "string",
                    "description": "The library the item is listed in.",
                    "example": "bookclerk-library"
                  },
                  "folderId": {
                    "type": "string",
                    "description": "The folder id: the library id.",
                    "example": "bookclerk-library"
                  },
                  "path": {
                    "type": "string",
                    "description": "A display path: the title.",
                    "example": "/the-first.m4b"
                  },
                  "relPath": {
                    "type": "string",
                    "description": "A display path: the title.",
                    "example": "the-first.m4b"
                  },
                  "isFile": {
                    "type": "boolean",
                    "description": "Always false: an item is a folder of tracks.",
                    "example": true
                  },
                  "mtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy last changed, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "ctimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "birthtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "addedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the item joined the library, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "updatedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When its record last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "isMissing": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "isInvalid": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "mediaType": {
                    "type": "string",
                    "description": "Always [`MEDIA_TYPE_BOOK`].",
                    "example": "book"
                  },
                  "media": {
                    "type": "object",
                    "description": "The book.",
                    "required": [
                      "id",
                      "metadata",
                      "tags",
                      "numTracks",
                      "numAudioFiles",
                      "numChapters",
                      "duration",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The media id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "libraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item id, when fetched expanded.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The book's metadata.",
                        "required": [
                          "title",
                          "titleIgnorePrefix",
                          "authors",
                          "authorName",
                          "authorNameLF",
                          "narrators",
                          "narratorName",
                          "series",
                          "seriesName",
                          "genres",
                          "explicit",
                          "abridged"
                        ],
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "The title.",
                            "example": "The First"
                          },
                          "titleIgnorePrefix": {
                            "type": "string",
                            "description": "The title for sorting.",
                            "example": "First, The"
                          },
                          "subtitle": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The subtitle, if any.",
                            "example": "A Novel"
                          },
                          "authors": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "An id and a name.",
                              "required": [
                                "id",
                                "name"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The entity's id.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "Its display name.",
                                  "example": "Ann Author"
                                }
                              }
                            },
                            "description": "The authors."
                          },
                          "authorName": {
                            "type": "string",
                            "description": "The authors' names joined with `, `.",
                            "example": "Ann Author"
                          },
                          "authorNameLF": {
                            "type": "string",
                            "description": "The authors' names, family name first, joined with `, `.",
                            "example": "Author, Ann"
                          },
                          "narrators": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The narrators' names.",
                            "example": [
                              "Nia Narrator"
                            ]
                          },
                          "narratorName": {
                            "type": "string",
                            "description": "The narrators' names joined with `, `.",
                            "example": "Nia Narrator"
                          },
                          "series": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A series an item belongs to, with the item's place in it.",
                              "required": [
                                "id",
                                "name"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The series id.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "The series name.",
                                  "example": "Ann Author"
                                },
                                "sequence": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                  "example": "1"
                                }
                              }
                            },
                            "description": "The series the book is in."
                          },
                          "seriesName": {
                            "type": "string",
                            "description": "The series names with the book's place (`Name #2`), joined.",
                            "example": "The Saga #1"
                          },
                          "genres": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Genres.",
                            "example": [
                              "Fantasy"
                            ]
                          },
                          "publishedYear": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The year of publication, as a string (`\"2019\"`).",
                            "example": "2024"
                          },
                          "publishedDate": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The date of publication, if known.",
                            "example": "2024-03-01"
                          },
                          "publisher": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The publisher.",
                            "example": "Example Press"
                          },
                          "description": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The description, as the library stores it.",
                            "example": "A short description."
                          },
                          "descriptionPlain": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The description with markup removed.",
                            "example": "A short description."
                          },
                          "isbn": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The ISBN, if known.",
                            "example": "9780000000002"
                          },
                          "asin": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The ASIN, if known.",
                            "example": "B000000000"
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The language.",
                            "example": "en-us"
                          },
                          "explicit": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "abridged": {
                            "type": "boolean",
                            "description": "Whether the edition is abridged.",
                            "example": false
                          }
                        }
                      },
                      "coverPath": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                        "example": "/player/api/items/li_8f14e45fceea467f/cover"
                      },
                      "tags": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Tags: none.",
                        "example": []
                      },
                      "numTracks": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Tracks in play order.",
                        "example": 1,
                        "minimum": 0
                      },
                      "numAudioFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Audio files.",
                        "example": 1,
                        "minimum": 0
                      },
                      "numChapters": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Chapters.",
                        "example": 0,
                        "minimum": 0
                      },
                      "duration": {
                        "type": "number",
                        "format": "double",
                        "description": "The book's length in seconds.",
                        "example": 36000.0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in its audio files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "audioFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "An audio file of a book.",
                          "required": [
                            "index",
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "manuallyVerified",
                            "exclude",
                            "duration",
                            "chapters",
                            "metaTags",
                            "mimeType"
                          ],
                          "properties": {
                            "index": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's place in play order, from 1.",
                              "example": 1,
                              "minimum": 0
                            },
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "trackNumFromMeta": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The track number the file's tags state: not read.",
                              "example": 1,
                              "minimum": 0
                            },
                            "discNumFromMeta": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The disc number the file's tags state: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "trackNumFromFilename": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The track number in the file name: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "discNumFromFilename": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The disc number in the file name: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "manuallyVerified": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "exclude": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "error": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "format": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The container format, such as `mp4` or `mp3`.",
                              "example": "MP4A"
                            },
                            "duration": {
                              "type": "number",
                              "format": "double",
                              "description": "The file's length in seconds.",
                              "example": 36000.0
                            },
                            "bitRate": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "Bits per second, if known.",
                              "example": 128000,
                              "minimum": 0
                            },
                            "language": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The file's language, if known.",
                              "example": "en-us"
                            },
                            "codec": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The codec, if known.",
                              "example": "aac"
                            },
                            "timeBase": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The time base, if known.",
                              "example": "1/44100"
                            },
                            "channels": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "Audio channels, if known.",
                              "example": 2,
                              "minimum": 0
                            },
                            "channelLayout": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The channel layout, if known.",
                              "example": "stereo"
                            },
                            "chapters": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "description": "A chapter of a book.",
                                "required": [
                                  "id",
                                  "start",
                                  "end",
                                  "title"
                                ],
                                "properties": {
                                  "id": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The chapter's place, from 0.",
                                    "example": 1,
                                    "minimum": 0
                                  },
                                  "start": {
                                    "type": "number",
                                    "format": "double",
                                    "description": "Where it starts, in seconds.",
                                    "example": 0.0
                                  },
                                  "end": {
                                    "type": "number",
                                    "format": "double",
                                    "description": "Where it ends, in seconds.",
                                    "example": 600.0
                                  },
                                  "title": {
                                    "type": "string",
                                    "description": "Its title.",
                                    "example": "The First"
                                  }
                                }
                              },
                              "description": "Chapters embedded in the file: none are read."
                            },
                            "embeddedCoverArt": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "metaTags": {
                              "type": "object",
                              "description": "Tags read from the file: none until the stored media probe reads\nthem."
                            },
                            "mimeType": {
                              "type": "string",
                              "description": "The file's media type, such as `audio/mp4`.",
                              "example": "audio/mp4"
                            }
                          }
                        },
                        "description": "The audio files, when fetched expanded."
                      },
                      "chapters": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A chapter of a book.",
                          "required": [
                            "id",
                            "start",
                            "end",
                            "title"
                          ],
                          "properties": {
                            "id": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The chapter's place, from 0.",
                              "example": 1,
                              "minimum": 0
                            },
                            "start": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it starts, in seconds.",
                              "example": 0.0
                            },
                            "end": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it ends, in seconds.",
                              "example": 600.0
                            },
                            "title": {
                              "type": "string",
                              "description": "Its title.",
                              "example": "The First"
                            }
                          }
                        },
                        "description": "The chapters, when fetched expanded."
                      },
                      "tracks": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A track with its place in the book.",
                          "required": [
                            "index",
                            "startOffset",
                            "duration",
                            "title",
                            "contentUrl",
                            "mimeType"
                          ],
                          "properties": {
                            "index": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The track's place in play order, from 1.",
                              "example": 1,
                              "minimum": 0
                            },
                            "startOffset": {
                              "type": "number",
                              "format": "double",
                              "description": "Where the track starts in the book, in seconds.",
                              "example": 0.0
                            },
                            "duration": {
                              "type": "number",
                              "format": "double",
                              "description": "The track's length in seconds.",
                              "example": 36000.0
                            },
                            "title": {
                              "type": "string",
                              "description": "The track's title: its file name.",
                              "example": "The First"
                            },
                            "contentUrl": {
                              "type": "string",
                              "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                              "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                            },
                            "mimeType": {
                              "type": "string",
                              "description": "The track's media type.",
                              "example": "audio/mp4"
                            },
                            "codec": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The codec, if known.",
                              "example": "aac"
                            },
                            "metadata": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          }
                        },
                        "description": "The tracks with their place in the book, when fetched expanded."
                      }
                    }
                  },
                  "numFiles": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Files in the item.",
                    "example": 1,
                    "minimum": 0
                  },
                  "size": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Bytes in all its files.",
                    "example": 100000,
                    "minimum": 0
                  },
                  "libraryFiles": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "description": "A file of an item, in the expanded item's `libraryFiles`.",
                      "required": [
                        "ino",
                        "metadata",
                        "addedAt",
                        "updatedAt",
                        "fileType"
                      ],
                      "properties": {
                        "ino": {
                          "type": "string",
                          "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                          "example": "0"
                        },
                        "metadata": {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        "addedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "updatedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "fileType": {
                          "type": "string",
                          "description": "Always `audio`.",
                          "example": "audio"
                        }
                      }
                    },
                    "description": "The item's files, when the item is fetched expanded."
                  },
                  "userMediaProgress": {
                    "oneOf": [
                      {
                        "type": "object",
                        "description": "The patron's progress, when the app asked for it.",
                        "required": [
                          "id",
                          "userId",
                          "libraryItemId",
                          "mediaItemId",
                          "mediaItemType",
                          "duration",
                          "progress",
                          "currentTime",
                          "isFinished",
                          "hideFromContinueListening",
                          "lastUpdate",
                          "startedAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The progress id: the item id (one record per patron and item).",
                            "example": "li_8f14e45fceea467f"
                          },
                          "userId": {
                            "type": "string",
                            "description": "The patron's id.",
                            "example": "42"
                          },
                          "libraryItemId": {
                            "type": "string",
                            "description": "The item id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "episodeId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "mediaItemId": {
                            "type": "string",
                            "description": "The media id: the item id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "mediaItemType": {
                            "type": "string",
                            "description": "Always `book`.",
                            "example": "book"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds, as last reported.",
                            "example": 36000.0
                          },
                          "progress": {
                            "type": "number",
                            "format": "double",
                            "description": "The share listened, from 0 to 1.",
                            "example": 0.05
                          },
                          "currentTime": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the patron is, in seconds.",
                            "example": 1830.5
                          },
                          "isFinished": {
                            "type": "boolean",
                            "description": "Whether the patron finished it.",
                            "example": false
                          },
                          "hideFromContinueListening": {
                            "type": "boolean",
                            "description": "Whether it is hidden from continue listening.",
                            "example": false
                          },
                          "ebookLocation": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "ebookProgress": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "format": "double",
                            "description": "Always null.",
                            "example": null
                          },
                          "lastUpdate": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the progress last changed, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "startedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the patron started, in epoch milliseconds.",
                            "example": 1763620000000
                          },
                          "finishedAt": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "When the patron finished, in epoch milliseconds.",
                            "example": null
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "seriesSequence": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The item's place in a series, on a series' book list.",
                    "example": "1"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "description": "The page's sessions, newest first."
    }
  }
}

Status 400: A query value is out of range.

Bad Request

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

GET /player/api/me/listening-stats

Sums the patron's listening, by item and by day.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Responses

  • 200Listening totals over the patron's latest 1000 sessions. Body: ListeningStats (application/json)6 fields
    • totalTimenumber (double)requiredSeconds listened in all.
    • itemsmap of string to ItemListeningrequiredSeconds listened per item, by item id.
    • daysmap of string to number (double)requiredSeconds listened per day, by YYYY-MM-DD.
    • dayOfWeekmap of string to number (double)requiredSeconds listened per weekday, by English weekday name.
    • todaynumber (double)requiredSeconds listened today.
    • recentSessionsarray of PlaybackSessionrequiredThe most recent sessions.
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 500The library could not be read. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/listening-stats' \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/listening-stats' `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.get(
    "http://127.0.0.1:8787/player/api/me/listening-stats",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/listening-stats", {
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .get("http://127.0.0.1:8787/player/api/me/listening-stats")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: Listening totals over the patron's latest 1000 sessions.

{
  "totalTime": 7200.0,
  "items": {},
  "days": {
    "2026-11-20": 1800.0
  },
  "dayOfWeek": {
    "Friday": 1800.0
  },
  "today": 1800.0,
  "recentSessions": [
    {
      "id": "li_8f14e45fceea467f",
      "userId": "42",
      "libraryId": "bookclerk-library",
      "libraryItemId": "li_8f14e45fceea467f",
      "bookId": "li_8f14e45fceea467f",
      "episodeId": null,
      "mediaType": "book",
      "mediaMetadata": {
        "title": "The First",
        "titleIgnorePrefix": "First, The",
        "subtitle": "A Novel",
        "authors": [],
        "authorName": "Ann Author",
        "authorNameLF": "Author, Ann",
        "narrators": [
          "Nia Narrator"
        ],
        "narratorName": "Nia Narrator",
        "series": [],
        "seriesName": "The Saga #1",
        "genres": [
          "Fantasy"
        ],
        "publishedYear": "2024",
        "publishedDate": "2024-03-01",
        "publisher": "Example Press",
        "description": "A short description.",
        "descriptionPlain": "A short description.",
        "isbn": "9780000000002",
        "asin": "B000000000",
        "language": "en-us",
        "explicit": false,
        "abridged": false
      },
      "chapters": [
        {
          "id": 1,
          "start": 0.0,
          "end": 600.0,
          "title": "The First"
        }
      ],
      "displayTitle": "The First",
      "displayAuthor": "Ann Author",
      "coverPath": "/player/api/items/li_8f14e45fceea467f/cover",
      "duration": 36000.0,
      "playMethod": 1,
      "mediaPlayer": "Absorb",
      "deviceInfo": {
        "deviceId": "pixel-8",
        "deviceName": "Pixel 8",
        "clientName": "Absorb"
      },
      "serverVersion": "2.17.0",
      "date": "2026-11-20",
      "dayOfWeek": "Friday",
      "timeListening": 60.0,
      "startTime": 1770.5,
      "currentTime": 1830.5,
      "startedAt": 1763620000000,
      "updatedAt": 1763630000000,
      "audioTracks": [
        {
          "index": 1,
          "startOffset": 0.0,
          "duration": 36000.0,
          "title": "The First",
          "contentUrl": "/player/api/items/li_8f14e45fceea467f/file/0",
          "mimeType": "audio/mp4"
        }
      ],
      "libraryItem": {
        "id": "li_8f14e45fceea467f",
        "ino": "0",
        "oldLibraryItemId": null,
        "libraryId": "bookclerk-library",
        "folderId": "bookclerk-library",
        "path": "/the-first.m4b",
        "relPath": "the-first.m4b",
        "isFile": true,
        "mtimeMs": 1763600000000,
        "ctimeMs": 1763600000000,
        "birthtimeMs": 1763600000000,
        "addedAt": 1763600000000,
        "updatedAt": 1763630000000,
        "isMissing": false,
        "isInvalid": false,
        "mediaType": "book",
        "media": {
          "id": "li_8f14e45fceea467f",
          "metadata": {
            "title": "The First",
            "titleIgnorePrefix": "First, The",
            "authors": [],
            "authorName": "Ann Author",
            "authorNameLF": "Author, Ann",
            "narrators": [
              "Nia Narrator"
            ],
            "narratorName": "Nia Narrator",
            "series": [],
            "seriesName": "The Saga #1",
            "genres": [
              "Fantasy"
            ],
            "explicit": false,
            "abridged": false
          },
          "tags": [],
          "numTracks": 1,
          "numAudioFiles": 1,
          "numChapters": 0,
          "duration": 36000.0,
          "size": 100000
        },
        "numFiles": 1,
        "size": 100000,
        "libraryFiles": [],
        "userMediaProgress": {
          "id": "li_8f14e45fceea467f",
          "userId": "42",
          "libraryItemId": "li_8f14e45fceea467f",
          "mediaItemId": "li_8f14e45fceea467f",
          "mediaItemType": "book",
          "duration": 36000.0,
          "progress": 0.05,
          "currentTime": 1830.5,
          "isFinished": false,
          "hideFromContinueListening": false,
          "lastUpdate": 1763630000000,
          "startedAt": 1763620000000
        },
        "seriesSequence": "1"
      }
    }
  ]
}

Schema:

{
  "type": "object",
  "description": "`GET /api/me/listening-stats`.",
  "required": [
    "totalTime",
    "items",
    "days",
    "dayOfWeek",
    "today",
    "recentSessions"
  ],
  "properties": {
    "totalTime": {
      "type": "number",
      "format": "double",
      "description": "Seconds listened in all.",
      "example": 7200.0
    },
    "items": {
      "type": "object",
      "description": "Seconds listened per item, by item id.",
      "additionalProperties": {
        "type": "object",
        "description": "Seconds listened to one item.",
        "required": [
          "id",
          "timeListening",
          "mediaMetadata"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The item id.",
            "example": "li_8f14e45fceea467f"
          },
          "timeListening": {
            "type": "number",
            "format": "double",
            "description": "Seconds listened.",
            "example": 60.0
          },
          "mediaMetadata": {
            "type": "object",
            "description": "The item's metadata.",
            "required": [
              "title",
              "titleIgnorePrefix",
              "authors",
              "authorName",
              "authorNameLF",
              "narrators",
              "narratorName",
              "series",
              "seriesName",
              "genres",
              "explicit",
              "abridged"
            ],
            "properties": {
              "title": {
                "type": "string",
                "description": "The title.",
                "example": "The First"
              },
              "titleIgnorePrefix": {
                "type": "string",
                "description": "The title for sorting.",
                "example": "First, The"
              },
              "subtitle": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The subtitle, if any.",
                "example": "A Novel"
              },
              "authors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "An id and a name.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The entity's id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "Its display name.",
                      "example": "Ann Author"
                    }
                  }
                },
                "description": "The authors."
              },
              "authorName": {
                "type": "string",
                "description": "The authors' names joined with `, `.",
                "example": "Ann Author"
              },
              "authorNameLF": {
                "type": "string",
                "description": "The authors' names, family name first, joined with `, `.",
                "example": "Author, Ann"
              },
              "narrators": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The narrators' names.",
                "example": [
                  "Nia Narrator"
                ]
              },
              "narratorName": {
                "type": "string",
                "description": "The narrators' names joined with `, `.",
                "example": "Nia Narrator"
              },
              "series": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A series an item belongs to, with the item's place in it.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The series id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "The series name.",
                      "example": "Ann Author"
                    },
                    "sequence": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                      "example": "1"
                    }
                  }
                },
                "description": "The series the book is in."
              },
              "seriesName": {
                "type": "string",
                "description": "The series names with the book's place (`Name #2`), joined.",
                "example": "The Saga #1"
              },
              "genres": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Genres.",
                "example": [
                  "Fantasy"
                ]
              },
              "publishedYear": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The year of publication, as a string (`\"2019\"`).",
                "example": "2024"
              },
              "publishedDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The date of publication, if known.",
                "example": "2024-03-01"
              },
              "publisher": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The publisher.",
                "example": "Example Press"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description, as the library stores it.",
                "example": "A short description."
              },
              "descriptionPlain": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description with markup removed.",
                "example": "A short description."
              },
              "isbn": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ISBN, if known.",
                "example": "9780000000002"
              },
              "asin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ASIN, if known.",
                "example": "B000000000"
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The language.",
                "example": "en-us"
              },
              "explicit": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "abridged": {
                "type": "boolean",
                "description": "Whether the edition is abridged.",
                "example": false
              }
            }
          }
        }
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {}
    },
    "days": {
      "type": "object",
      "description": "Seconds listened per day, by `YYYY-MM-DD`.",
      "additionalProperties": {
        "type": "number",
        "format": "double"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "2026-11-20": 1800.0
      }
    },
    "dayOfWeek": {
      "type": "object",
      "description": "Seconds listened per weekday, by English weekday name.",
      "additionalProperties": {
        "type": "number",
        "format": "double"
      },
      "propertyNames": {
        "type": "string"
      },
      "example": {
        "Friday": 1800.0
      }
    },
    "today": {
      "type": "number",
      "format": "double",
      "description": "Seconds listened today.",
      "example": 1800.0
    },
    "recentSessions": {
      "type": "array",
      "items": {
        "type": "object",
        "description": "A playback session, as `POST /api/items/{id}/play` answers.",
        "required": [
          "id",
          "userId",
          "libraryId",
          "libraryItemId",
          "bookId",
          "mediaType",
          "mediaMetadata",
          "chapters",
          "displayTitle",
          "displayAuthor",
          "duration",
          "playMethod",
          "mediaPlayer",
          "deviceInfo",
          "serverVersion",
          "date",
          "dayOfWeek",
          "timeListening",
          "startTime",
          "currentTime",
          "startedAt",
          "updatedAt",
          "audioTracks"
        ],
        "properties": {
          "id": {
            "type": "string",
            "description": "The session id; apps send it back to sync and close.",
            "example": "li_8f14e45fceea467f"
          },
          "userId": {
            "type": "string",
            "description": "The patron's id.",
            "example": "42"
          },
          "libraryId": {
            "type": "string",
            "description": "The library id.",
            "example": "bookclerk-library"
          },
          "libraryItemId": {
            "type": "string",
            "description": "The item id.",
            "example": "li_8f14e45fceea467f"
          },
          "bookId": {
            "type": "string",
            "description": "The media id: the item id.",
            "example": "li_8f14e45fceea467f"
          },
          "episodeId": {
            "type": [
              "string",
              "null"
            ],
            "description": "Always null.",
            "example": null
          },
          "mediaType": {
            "type": "string",
            "description": "Always [`MEDIA_TYPE_BOOK`].",
            "example": "book"
          },
          "mediaMetadata": {
            "type": "object",
            "description": "The book's metadata.",
            "required": [
              "title",
              "titleIgnorePrefix",
              "authors",
              "authorName",
              "authorNameLF",
              "narrators",
              "narratorName",
              "series",
              "seriesName",
              "genres",
              "explicit",
              "abridged"
            ],
            "properties": {
              "title": {
                "type": "string",
                "description": "The title.",
                "example": "The First"
              },
              "titleIgnorePrefix": {
                "type": "string",
                "description": "The title for sorting.",
                "example": "First, The"
              },
              "subtitle": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The subtitle, if any.",
                "example": "A Novel"
              },
              "authors": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "An id and a name.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The entity's id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "Its display name.",
                      "example": "Ann Author"
                    }
                  }
                },
                "description": "The authors."
              },
              "authorName": {
                "type": "string",
                "description": "The authors' names joined with `, `.",
                "example": "Ann Author"
              },
              "authorNameLF": {
                "type": "string",
                "description": "The authors' names, family name first, joined with `, `.",
                "example": "Author, Ann"
              },
              "narrators": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "The narrators' names.",
                "example": [
                  "Nia Narrator"
                ]
              },
              "narratorName": {
                "type": "string",
                "description": "The narrators' names joined with `, `.",
                "example": "Nia Narrator"
              },
              "series": {
                "type": "array",
                "items": {
                  "type": "object",
                  "description": "A series an item belongs to, with the item's place in it.",
                  "required": [
                    "id",
                    "name"
                  ],
                  "properties": {
                    "id": {
                      "type": "string",
                      "description": "The series id.",
                      "example": "li_8f14e45fceea467f"
                    },
                    "name": {
                      "type": "string",
                      "description": "The series name.",
                      "example": "Ann Author"
                    },
                    "sequence": {
                      "type": [
                        "string",
                        "null"
                      ],
                      "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                      "example": "1"
                    }
                  }
                },
                "description": "The series the book is in."
              },
              "seriesName": {
                "type": "string",
                "description": "The series names with the book's place (`Name #2`), joined.",
                "example": "The Saga #1"
              },
              "genres": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Genres.",
                "example": [
                  "Fantasy"
                ]
              },
              "publishedYear": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The year of publication, as a string (`\"2019\"`).",
                "example": "2024"
              },
              "publishedDate": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The date of publication, if known.",
                "example": "2024-03-01"
              },
              "publisher": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The publisher.",
                "example": "Example Press"
              },
              "description": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description, as the library stores it.",
                "example": "A short description."
              },
              "descriptionPlain": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The description with markup removed.",
                "example": "A short description."
              },
              "isbn": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ISBN, if known.",
                "example": "9780000000002"
              },
              "asin": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The ASIN, if known.",
                "example": "B000000000"
              },
              "language": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The language.",
                "example": "en-us"
              },
              "explicit": {
                "type": "boolean",
                "description": "Always false.",
                "example": false
              },
              "abridged": {
                "type": "boolean",
                "description": "Whether the edition is abridged.",
                "example": false
              }
            }
          },
          "chapters": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A chapter of a book.",
              "required": [
                "id",
                "start",
                "end",
                "title"
              ],
              "properties": {
                "id": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The chapter's place, from 0.",
                  "example": 1,
                  "minimum": 0
                },
                "start": {
                  "type": "number",
                  "format": "double",
                  "description": "Where it starts, in seconds.",
                  "example": 0.0
                },
                "end": {
                  "type": "number",
                  "format": "double",
                  "description": "Where it ends, in seconds.",
                  "example": 600.0
                },
                "title": {
                  "type": "string",
                  "description": "Its title.",
                  "example": "The First"
                }
              }
            },
            "description": "The book's chapters."
          },
          "displayTitle": {
            "type": "string",
            "description": "The title apps show.",
            "example": "The First"
          },
          "displayAuthor": {
            "type": "string",
            "description": "The author apps show.",
            "example": "Ann Author"
          },
          "coverPath": {
            "type": [
              "string",
              "null"
            ],
            "description": "A cover path apps test for presence.",
            "example": "/player/api/items/li_8f14e45fceea467f/cover"
          },
          "duration": {
            "type": "number",
            "format": "double",
            "description": "The book's length in seconds.",
            "example": 36000.0
          },
          "playMethod": {
            "type": "integer",
            "format": "int32",
            "description": "How the app plays: 0, direct play of the stored files.",
            "example": 1,
            "minimum": 0
          },
          "mediaPlayer": {
            "type": "string",
            "description": "The player the app reported.",
            "example": "Absorb"
          },
          "deviceInfo": {
            "type": "object",
            "description": "The device the session was opened from.",
            "required": [
              "deviceId"
            ],
            "properties": {
              "deviceId": {
                "type": "string",
                "description": "The device's id: the card's session id.",
                "example": "pixel-8"
              },
              "deviceName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The device name the app reported, if any.",
                "example": "Pixel 8"
              },
              "clientName": {
                "type": [
                  "string",
                  "null"
                ],
                "description": "The app's name, if reported.",
                "example": "Absorb"
              }
            }
          },
          "serverVersion": {
            "type": "string",
            "description": "[`crate::COMPATIBLE_SERVER_VERSION`].",
            "example": "2.17.0"
          },
          "date": {
            "type": "string",
            "description": "The day the session started, `YYYY-MM-DD` in UTC.",
            "example": "2026-11-20"
          },
          "dayOfWeek": {
            "type": "string",
            "description": "The weekday the session started, in English.",
            "example": "Friday"
          },
          "timeListening": {
            "type": "number",
            "format": "double",
            "description": "Seconds listened in this session.",
            "example": 60.0
          },
          "startTime": {
            "type": "number",
            "format": "double",
            "description": "Where the session started, in seconds.",
            "example": 1770.5
          },
          "currentTime": {
            "type": "number",
            "format": "double",
            "description": "Where the patron is, in seconds.",
            "example": 1830.5
          },
          "startedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When the session started, in epoch milliseconds.",
            "example": 1763620000000
          },
          "updatedAt": {
            "type": "integer",
            "format": "int64",
            "description": "When it last synced, in epoch milliseconds.",
            "example": 1763630000000
          },
          "audioTracks": {
            "type": "array",
            "items": {
              "type": "object",
              "description": "A track with its place in the book.",
              "required": [
                "index",
                "startOffset",
                "duration",
                "title",
                "contentUrl",
                "mimeType"
              ],
              "properties": {
                "index": {
                  "type": "integer",
                  "format": "int64",
                  "description": "The track's place in play order, from 1.",
                  "example": 1,
                  "minimum": 0
                },
                "startOffset": {
                  "type": "number",
                  "format": "double",
                  "description": "Where the track starts in the book, in seconds.",
                  "example": 0.0
                },
                "duration": {
                  "type": "number",
                  "format": "double",
                  "description": "The track's length in seconds.",
                  "example": 36000.0
                },
                "title": {
                  "type": "string",
                  "description": "The track's title: its file name.",
                  "example": "The First"
                },
                "contentUrl": {
                  "type": "string",
                  "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                  "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                },
                "mimeType": {
                  "type": "string",
                  "description": "The track's media type.",
                  "example": "audio/mp4"
                },
                "codec": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "description": "The codec, if known.",
                  "example": "aac"
                },
                "metadata": {
                  "oneOf": [
                    {
                      "type": "object",
                      "description": "The file's name, size and times.",
                      "required": [
                        "filename",
                        "ext",
                        "path",
                        "relPath",
                        "size",
                        "mtimeMs",
                        "ctimeMs",
                        "birthtimeMs"
                      ],
                      "properties": {
                        "filename": {
                          "type": "string",
                          "description": "The file name.",
                          "example": "the-first.m4b"
                        },
                        "ext": {
                          "type": "string",
                          "description": "The extension with its dot (`.m4b`).",
                          "example": ".m4b"
                        },
                        "path": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "/the-first.m4b"
                        },
                        "relPath": {
                          "type": "string",
                          "description": "A display path: the file name.",
                          "example": "the-first.m4b"
                        },
                        "size": {
                          "type": "integer",
                          "format": "int64",
                          "description": "The file's size in bytes.",
                          "example": 100000,
                          "minimum": 0
                        },
                        "mtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "ctimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "birthtimeMs": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        }
                      }
                    },
                    {
                      "type": "null"
                    }
                  ]
                }
              }
            },
            "description": "The tracks to play, in order."
          },
          "libraryItem": {
            "oneOf": [
              {
                "type": "object",
                "description": "The item, expanded.",
                "required": [
                  "id",
                  "ino",
                  "libraryId",
                  "folderId",
                  "path",
                  "relPath",
                  "isFile",
                  "mtimeMs",
                  "ctimeMs",
                  "birthtimeMs",
                  "addedAt",
                  "updatedAt",
                  "isMissing",
                  "isInvalid",
                  "mediaType",
                  "media",
                  "numFiles",
                  "size"
                ],
                "properties": {
                  "id": {
                    "type": "string",
                    "description": "The item id: the edition id.",
                    "example": "li_8f14e45fceea467f"
                  },
                  "ino": {
                    "type": "string",
                    "description": "The item's inode as apps expect one: the edition id again.",
                    "example": "0"
                  },
                  "oldLibraryItemId": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "Always null.",
                    "example": null
                  },
                  "libraryId": {
                    "type": "string",
                    "description": "The library the item is listed in.",
                    "example": "bookclerk-library"
                  },
                  "folderId": {
                    "type": "string",
                    "description": "The folder id: the library id.",
                    "example": "bookclerk-library"
                  },
                  "path": {
                    "type": "string",
                    "description": "A display path: the title.",
                    "example": "/the-first.m4b"
                  },
                  "relPath": {
                    "type": "string",
                    "description": "A display path: the title.",
                    "example": "the-first.m4b"
                  },
                  "isFile": {
                    "type": "boolean",
                    "description": "Always false: an item is a folder of tracks.",
                    "example": true
                  },
                  "mtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy last changed, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "ctimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "birthtimeMs": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the copy was stored, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "addedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When the item joined the library, in epoch milliseconds.",
                    "example": 1763600000000
                  },
                  "updatedAt": {
                    "type": "integer",
                    "format": "int64",
                    "description": "When its record last changed, in epoch milliseconds.",
                    "example": 1763630000000
                  },
                  "isMissing": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "isInvalid": {
                    "type": "boolean",
                    "description": "Always false.",
                    "example": false
                  },
                  "mediaType": {
                    "type": "string",
                    "description": "Always [`MEDIA_TYPE_BOOK`].",
                    "example": "book"
                  },
                  "media": {
                    "type": "object",
                    "description": "The book.",
                    "required": [
                      "id",
                      "metadata",
                      "tags",
                      "numTracks",
                      "numAudioFiles",
                      "numChapters",
                      "duration",
                      "size"
                    ],
                    "properties": {
                      "id": {
                        "type": "string",
                        "description": "The media id: the edition id.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "libraryItemId": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "The item id, when fetched expanded.",
                        "example": "li_8f14e45fceea467f"
                      },
                      "metadata": {
                        "type": "object",
                        "description": "The book's metadata.",
                        "required": [
                          "title",
                          "titleIgnorePrefix",
                          "authors",
                          "authorName",
                          "authorNameLF",
                          "narrators",
                          "narratorName",
                          "series",
                          "seriesName",
                          "genres",
                          "explicit",
                          "abridged"
                        ],
                        "properties": {
                          "title": {
                            "type": "string",
                            "description": "The title.",
                            "example": "The First"
                          },
                          "titleIgnorePrefix": {
                            "type": "string",
                            "description": "The title for sorting.",
                            "example": "First, The"
                          },
                          "subtitle": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The subtitle, if any.",
                            "example": "A Novel"
                          },
                          "authors": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "An id and a name.",
                              "required": [
                                "id",
                                "name"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The entity's id.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "Its display name.",
                                  "example": "Ann Author"
                                }
                              }
                            },
                            "description": "The authors."
                          },
                          "authorName": {
                            "type": "string",
                            "description": "The authors' names joined with `, `.",
                            "example": "Ann Author"
                          },
                          "authorNameLF": {
                            "type": "string",
                            "description": "The authors' names, family name first, joined with `, `.",
                            "example": "Author, Ann"
                          },
                          "narrators": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "The narrators' names.",
                            "example": [
                              "Nia Narrator"
                            ]
                          },
                          "narratorName": {
                            "type": "string",
                            "description": "The narrators' names joined with `, `.",
                            "example": "Nia Narrator"
                          },
                          "series": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "description": "A series an item belongs to, with the item's place in it.",
                              "required": [
                                "id",
                                "name"
                              ],
                              "properties": {
                                "id": {
                                  "type": "string",
                                  "description": "The series id.",
                                  "example": "li_8f14e45fceea467f"
                                },
                                "name": {
                                  "type": "string",
                                  "description": "The series name.",
                                  "example": "Ann Author"
                                },
                                "sequence": {
                                  "type": [
                                    "string",
                                    "null"
                                  ],
                                  "description": "The item's place in the series as the library writes it (`1`,\n`2.5`), if known.",
                                  "example": "1"
                                }
                              }
                            },
                            "description": "The series the book is in."
                          },
                          "seriesName": {
                            "type": "string",
                            "description": "The series names with the book's place (`Name #2`), joined.",
                            "example": "The Saga #1"
                          },
                          "genres": {
                            "type": "array",
                            "items": {
                              "type": "string"
                            },
                            "description": "Genres.",
                            "example": [
                              "Fantasy"
                            ]
                          },
                          "publishedYear": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The year of publication, as a string (`\"2019\"`).",
                            "example": "2024"
                          },
                          "publishedDate": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The date of publication, if known.",
                            "example": "2024-03-01"
                          },
                          "publisher": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The publisher.",
                            "example": "Example Press"
                          },
                          "description": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The description, as the library stores it.",
                            "example": "A short description."
                          },
                          "descriptionPlain": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The description with markup removed.",
                            "example": "A short description."
                          },
                          "isbn": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The ISBN, if known.",
                            "example": "9780000000002"
                          },
                          "asin": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The ASIN, if known.",
                            "example": "B000000000"
                          },
                          "language": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "The language.",
                            "example": "en-us"
                          },
                          "explicit": {
                            "type": "boolean",
                            "description": "Always false.",
                            "example": false
                          },
                          "abridged": {
                            "type": "boolean",
                            "description": "Whether the edition is abridged.",
                            "example": false
                          }
                        }
                      },
                      "coverPath": {
                        "type": [
                          "string",
                          "null"
                        ],
                        "description": "A cover path apps only test for presence; covers are fetched from\n`/api/items/{id}/cover`.",
                        "example": "/player/api/items/li_8f14e45fceea467f/cover"
                      },
                      "tags": {
                        "type": "array",
                        "items": {
                          "type": "string"
                        },
                        "description": "Tags: none.",
                        "example": []
                      },
                      "numTracks": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Tracks in play order.",
                        "example": 1,
                        "minimum": 0
                      },
                      "numAudioFiles": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Audio files.",
                        "example": 1,
                        "minimum": 0
                      },
                      "numChapters": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Chapters.",
                        "example": 0,
                        "minimum": 0
                      },
                      "duration": {
                        "type": "number",
                        "format": "double",
                        "description": "The book's length in seconds.",
                        "example": 36000.0
                      },
                      "size": {
                        "type": "integer",
                        "format": "int64",
                        "description": "Bytes in its audio files.",
                        "example": 100000,
                        "minimum": 0
                      },
                      "audioFiles": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "An audio file of a book.",
                          "required": [
                            "index",
                            "ino",
                            "metadata",
                            "addedAt",
                            "updatedAt",
                            "manuallyVerified",
                            "exclude",
                            "duration",
                            "chapters",
                            "metaTags",
                            "mimeType"
                          ],
                          "properties": {
                            "index": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's place in play order, from 1.",
                              "example": 1,
                              "minimum": 0
                            },
                            "ino": {
                              "type": "string",
                              "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                              "example": "0"
                            },
                            "metadata": {
                              "type": "object",
                              "description": "The file's name, size and times.",
                              "required": [
                                "filename",
                                "ext",
                                "path",
                                "relPath",
                                "size",
                                "mtimeMs",
                                "ctimeMs",
                                "birthtimeMs"
                              ],
                              "properties": {
                                "filename": {
                                  "type": "string",
                                  "description": "The file name.",
                                  "example": "the-first.m4b"
                                },
                                "ext": {
                                  "type": "string",
                                  "description": "The extension with its dot (`.m4b`).",
                                  "example": ".m4b"
                                },
                                "path": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "/the-first.m4b"
                                },
                                "relPath": {
                                  "type": "string",
                                  "description": "A display path: the file name.",
                                  "example": "the-first.m4b"
                                },
                                "size": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "The file's size in bytes.",
                                  "example": 100000,
                                  "minimum": 0
                                },
                                "mtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "ctimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                },
                                "birthtimeMs": {
                                  "type": "integer",
                                  "format": "int64",
                                  "description": "When the file was stored, in epoch milliseconds.",
                                  "example": 1763600000000
                                }
                              }
                            },
                            "addedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "updatedAt": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763630000000
                            },
                            "trackNumFromMeta": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The track number the file's tags state: not read.",
                              "example": 1,
                              "minimum": 0
                            },
                            "discNumFromMeta": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The disc number the file's tags state: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "trackNumFromFilename": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The track number in the file name: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "discNumFromFilename": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "The disc number in the file name: not read.",
                              "example": null,
                              "minimum": 0
                            },
                            "manuallyVerified": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "exclude": {
                              "type": "boolean",
                              "description": "Always false.",
                              "example": false
                            },
                            "error": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "format": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The container format, such as `mp4` or `mp3`.",
                              "example": "MP4A"
                            },
                            "duration": {
                              "type": "number",
                              "format": "double",
                              "description": "The file's length in seconds.",
                              "example": 36000.0
                            },
                            "bitRate": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "Bits per second, if known.",
                              "example": 128000,
                              "minimum": 0
                            },
                            "language": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The file's language, if known.",
                              "example": "en-us"
                            },
                            "codec": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The codec, if known.",
                              "example": "aac"
                            },
                            "timeBase": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The time base, if known.",
                              "example": "1/44100"
                            },
                            "channels": {
                              "type": [
                                "integer",
                                "null"
                              ],
                              "format": "int64",
                              "description": "Audio channels, if known.",
                              "example": 2,
                              "minimum": 0
                            },
                            "channelLayout": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The channel layout, if known.",
                              "example": "stereo"
                            },
                            "chapters": {
                              "type": "array",
                              "items": {
                                "type": "object",
                                "description": "A chapter of a book.",
                                "required": [
                                  "id",
                                  "start",
                                  "end",
                                  "title"
                                ],
                                "properties": {
                                  "id": {
                                    "type": "integer",
                                    "format": "int64",
                                    "description": "The chapter's place, from 0.",
                                    "example": 1,
                                    "minimum": 0
                                  },
                                  "start": {
                                    "type": "number",
                                    "format": "double",
                                    "description": "Where it starts, in seconds.",
                                    "example": 0.0
                                  },
                                  "end": {
                                    "type": "number",
                                    "format": "double",
                                    "description": "Where it ends, in seconds.",
                                    "example": 600.0
                                  },
                                  "title": {
                                    "type": "string",
                                    "description": "Its title.",
                                    "example": "The First"
                                  }
                                }
                              },
                              "description": "Chapters embedded in the file: none are read."
                            },
                            "embeddedCoverArt": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "Always null.",
                              "example": null
                            },
                            "metaTags": {
                              "type": "object",
                              "description": "Tags read from the file: none until the stored media probe reads\nthem."
                            },
                            "mimeType": {
                              "type": "string",
                              "description": "The file's media type, such as `audio/mp4`.",
                              "example": "audio/mp4"
                            }
                          }
                        },
                        "description": "The audio files, when fetched expanded."
                      },
                      "chapters": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A chapter of a book.",
                          "required": [
                            "id",
                            "start",
                            "end",
                            "title"
                          ],
                          "properties": {
                            "id": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The chapter's place, from 0.",
                              "example": 1,
                              "minimum": 0
                            },
                            "start": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it starts, in seconds.",
                              "example": 0.0
                            },
                            "end": {
                              "type": "number",
                              "format": "double",
                              "description": "Where it ends, in seconds.",
                              "example": 600.0
                            },
                            "title": {
                              "type": "string",
                              "description": "Its title.",
                              "example": "The First"
                            }
                          }
                        },
                        "description": "The chapters, when fetched expanded."
                      },
                      "tracks": {
                        "type": [
                          "array",
                          "null"
                        ],
                        "items": {
                          "type": "object",
                          "description": "A track with its place in the book.",
                          "required": [
                            "index",
                            "startOffset",
                            "duration",
                            "title",
                            "contentUrl",
                            "mimeType"
                          ],
                          "properties": {
                            "index": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The track's place in play order, from 1.",
                              "example": 1,
                              "minimum": 0
                            },
                            "startOffset": {
                              "type": "number",
                              "format": "double",
                              "description": "Where the track starts in the book, in seconds.",
                              "example": 0.0
                            },
                            "duration": {
                              "type": "number",
                              "format": "double",
                              "description": "The track's length in seconds.",
                              "example": 36000.0
                            },
                            "title": {
                              "type": "string",
                              "description": "The track's title: its file name.",
                              "example": "The First"
                            },
                            "contentUrl": {
                              "type": "string",
                              "description": "The path the track streams from, under the API's base address\n(`/api/items/{id}/file/{ino}`); apps add `?token=`.",
                              "example": "/player/api/items/li_8f14e45fceea467f/file/0"
                            },
                            "mimeType": {
                              "type": "string",
                              "description": "The track's media type.",
                              "example": "audio/mp4"
                            },
                            "codec": {
                              "type": [
                                "string",
                                "null"
                              ],
                              "description": "The codec, if known.",
                              "example": "aac"
                            },
                            "metadata": {
                              "oneOf": [
                                {
                                  "type": "object",
                                  "description": "The file's name, size and times.",
                                  "required": [
                                    "filename",
                                    "ext",
                                    "path",
                                    "relPath",
                                    "size",
                                    "mtimeMs",
                                    "ctimeMs",
                                    "birthtimeMs"
                                  ],
                                  "properties": {
                                    "filename": {
                                      "type": "string",
                                      "description": "The file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "ext": {
                                      "type": "string",
                                      "description": "The extension with its dot (`.m4b`).",
                                      "example": ".m4b"
                                    },
                                    "path": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "/the-first.m4b"
                                    },
                                    "relPath": {
                                      "type": "string",
                                      "description": "A display path: the file name.",
                                      "example": "the-first.m4b"
                                    },
                                    "size": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "The file's size in bytes.",
                                      "example": 100000,
                                      "minimum": 0
                                    },
                                    "mtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "ctimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    },
                                    "birthtimeMs": {
                                      "type": "integer",
                                      "format": "int64",
                                      "description": "When the file was stored, in epoch milliseconds.",
                                      "example": 1763600000000
                                    }
                                  }
                                },
                                {
                                  "type": "null"
                                }
                              ]
                            }
                          }
                        },
                        "description": "The tracks with their place in the book, when fetched expanded."
                      }
                    }
                  },
                  "numFiles": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Files in the item.",
                    "example": 1,
                    "minimum": 0
                  },
                  "size": {
                    "type": "integer",
                    "format": "int64",
                    "description": "Bytes in all its files.",
                    "example": 100000,
                    "minimum": 0
                  },
                  "libraryFiles": {
                    "type": [
                      "array",
                      "null"
                    ],
                    "items": {
                      "type": "object",
                      "description": "A file of an item, in the expanded item's `libraryFiles`.",
                      "required": [
                        "ino",
                        "metadata",
                        "addedAt",
                        "updatedAt",
                        "fileType"
                      ],
                      "properties": {
                        "ino": {
                          "type": "string",
                          "description": "The file's `ino` ([`crate::ids::file_ino`]).",
                          "example": "0"
                        },
                        "metadata": {
                          "type": "object",
                          "description": "The file's name, size and times.",
                          "required": [
                            "filename",
                            "ext",
                            "path",
                            "relPath",
                            "size",
                            "mtimeMs",
                            "ctimeMs",
                            "birthtimeMs"
                          ],
                          "properties": {
                            "filename": {
                              "type": "string",
                              "description": "The file name.",
                              "example": "the-first.m4b"
                            },
                            "ext": {
                              "type": "string",
                              "description": "The extension with its dot (`.m4b`).",
                              "example": ".m4b"
                            },
                            "path": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "/the-first.m4b"
                            },
                            "relPath": {
                              "type": "string",
                              "description": "A display path: the file name.",
                              "example": "the-first.m4b"
                            },
                            "size": {
                              "type": "integer",
                              "format": "int64",
                              "description": "The file's size in bytes.",
                              "example": 100000,
                              "minimum": 0
                            },
                            "mtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "ctimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            },
                            "birthtimeMs": {
                              "type": "integer",
                              "format": "int64",
                              "description": "When the file was stored, in epoch milliseconds.",
                              "example": 1763600000000
                            }
                          }
                        },
                        "addedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763600000000
                        },
                        "updatedAt": {
                          "type": "integer",
                          "format": "int64",
                          "description": "When the file was stored, in epoch milliseconds.",
                          "example": 1763630000000
                        },
                        "fileType": {
                          "type": "string",
                          "description": "Always `audio`.",
                          "example": "audio"
                        }
                      }
                    },
                    "description": "The item's files, when the item is fetched expanded."
                  },
                  "userMediaProgress": {
                    "oneOf": [
                      {
                        "type": "object",
                        "description": "The patron's progress, when the app asked for it.",
                        "required": [
                          "id",
                          "userId",
                          "libraryItemId",
                          "mediaItemId",
                          "mediaItemType",
                          "duration",
                          "progress",
                          "currentTime",
                          "isFinished",
                          "hideFromContinueListening",
                          "lastUpdate",
                          "startedAt"
                        ],
                        "properties": {
                          "id": {
                            "type": "string",
                            "description": "The progress id: the item id (one record per patron and item).",
                            "example": "li_8f14e45fceea467f"
                          },
                          "userId": {
                            "type": "string",
                            "description": "The patron's id.",
                            "example": "42"
                          },
                          "libraryItemId": {
                            "type": "string",
                            "description": "The item id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "episodeId": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "mediaItemId": {
                            "type": "string",
                            "description": "The media id: the item id.",
                            "example": "li_8f14e45fceea467f"
                          },
                          "mediaItemType": {
                            "type": "string",
                            "description": "Always `book`.",
                            "example": "book"
                          },
                          "duration": {
                            "type": "number",
                            "format": "double",
                            "description": "The book's length in seconds, as last reported.",
                            "example": 36000.0
                          },
                          "progress": {
                            "type": "number",
                            "format": "double",
                            "description": "The share listened, from 0 to 1.",
                            "example": 0.05
                          },
                          "currentTime": {
                            "type": "number",
                            "format": "double",
                            "description": "Where the patron is, in seconds.",
                            "example": 1830.5
                          },
                          "isFinished": {
                            "type": "boolean",
                            "description": "Whether the patron finished it.",
                            "example": false
                          },
                          "hideFromContinueListening": {
                            "type": "boolean",
                            "description": "Whether it is hidden from continue listening.",
                            "example": false
                          },
                          "ebookLocation": {
                            "type": [
                              "string",
                              "null"
                            ],
                            "description": "Always null.",
                            "example": null
                          },
                          "ebookProgress": {
                            "type": [
                              "number",
                              "null"
                            ],
                            "format": "double",
                            "description": "Always null.",
                            "example": null
                          },
                          "lastUpdate": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the progress last changed, in epoch milliseconds.",
                            "example": 1763630000000
                          },
                          "startedAt": {
                            "type": "integer",
                            "format": "int64",
                            "description": "When the patron started, in epoch milliseconds.",
                            "example": 1763620000000
                          },
                          "finishedAt": {
                            "type": [
                              "integer",
                              "null"
                            ],
                            "format": "int64",
                            "description": "When the patron finished, in epoch milliseconds.",
                            "example": null
                          }
                        }
                      },
                      {
                        "type": "null"
                      }
                    ]
                  },
                  "seriesSequence": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "description": "The item's place in a series, on a series' book list.",
                    "example": "1"
                  }
                }
              },
              {
                "type": "null"
              }
            ]
          }
        }
      },
      "description": "The most recent sessions."
    }
  }
}

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 500: The library could not be read.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

POST /player/api/me/item/{id}/bookmark

Adds a bookmark to an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Request body

The place, in seconds, and a title.

application/json: BookmarkBody

  • timenumber (double)requiredThe place, in seconds; on PATCH, which bookmark to rename.
  • titlestring or nullThe bookmark's title.

Responses

  • 200The bookmark. Body: Bookmark (application/json)4 fields
    • libraryItemIdstringrequiredThe item it is in.
    • titlestringrequiredIts title.
    • timenumber (double)requiredWhere it is, in seconds.
    • createdAtinteger (int64)requiredWhen it was made, in epoch milliseconds.
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item. Body: string (text/plain)
  • 409The patron has as many bookmarks as the library keeps. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' \
    -X POST \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{"time": 1830.0}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' `
    -Method Post `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{"time": 1830.0}'
import requests

response = requests.post(
    "http://127.0.0.1:8787/player/api/me/item/<id>/bookmark",
    headers={"Authorization": "Bearer <playerToken>"},
    json={"time": 1830.0},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark", {
  method: "POST",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"time": 1830.0}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .post("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({"time": 1830.0}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The bookmark.

{
  "libraryItemId": "li_8f14e45fceea467f",
  "title": "The First",
  "time": 1830.0,
  "createdAt": 1763600000000
}

Schema:

{
  "type": "object",
  "description": "A bookmark.",
  "required": [
    "libraryItemId",
    "title",
    "time",
    "createdAt"
  ],
  "properties": {
    "libraryItemId": {
      "type": "string",
      "description": "The item it is in.",
      "example": "li_8f14e45fceea467f"
    },
    "title": {
      "type": "string",
      "description": "Its title.",
      "example": "The First"
    },
    "time": {
      "type": "number",
      "format": "double",
      "description": "Where it is, in seconds.",
      "example": 1830.0
    },
    "createdAt": {
      "type": "integer",
      "format": "int64",
      "description": "When it was made, in epoch milliseconds.",
      "example": 1763600000000
    }
  }
}

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item.

Not Found

Schema:

A text/plain body: a string.

Status 409: The patron has as many bookmarks as the library keeps.

Too many bookmarks

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `time` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

PATCH /player/api/me/item/{id}/bookmark

Renames the bookmark at a time in an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.

Request body

Which bookmark, by its place in seconds, and its new title.

application/json: BookmarkBody

  • timenumber (double)requiredThe place, in seconds; on PATCH, which bookmark to rename.
  • titlestring or nullThe bookmark's title.

Responses

  • 200The bookmark. Body: Bookmark (application/json)4 fields
    • libraryItemIdstringrequiredThe item it is in.
    • titlestringrequiredIts title.
    • timenumber (double)requiredWhere it is, in seconds.
    • createdAtinteger (int64)requiredWhen it was made, in epoch milliseconds.
  • 400The body is malformed. As text/plain, when the body is not syntactically valid JSON. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item or bookmark. Body: string (text/plain)
  • 413The body is too long. Body: string (text/plain)
  • 415The request did not declare a JSON body. Body: string (text/plain)
  • 422The JSON does not fit the body: a missing field, a wrong type or an unknown shape. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' \
    -X PATCH \
    -H 'Authorization: Bearer <playerToken>' \
    -H 'Content-Type: application/json' \
    -d '{"time": 1830.0}'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark' `
    -Method Patch `
    -Headers @{ Authorization = 'Bearer <playerToken>' } `
    -ContentType 'application/json' `
    -Body '{"time": 1830.0}'
import requests

response = requests.patch(
    "http://127.0.0.1:8787/player/api/me/item/<id>/bookmark",
    headers={"Authorization": "Bearer <playerToken>"},
    json={"time": 1830.0},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark", {
  method: "PATCH",
  headers: { Authorization: "Bearer <playerToken>", "Content-Type": "application/json" },
  body: JSON.stringify({"time": 1830.0}),
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .patch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark")
    .header("Authorization", "Bearer <playerToken>")
    .json(&serde_json::json!({"time": 1830.0}))
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: The bookmark.

{
  "libraryItemId": "li_8f14e45fceea467f",
  "title": "The First",
  "time": 1830.0,
  "createdAt": 1763600000000
}

Schema:

{
  "type": "object",
  "description": "A bookmark.",
  "required": [
    "libraryItemId",
    "title",
    "time",
    "createdAt"
  ],
  "properties": {
    "libraryItemId": {
      "type": "string",
      "description": "The item it is in.",
      "example": "li_8f14e45fceea467f"
    },
    "title": {
      "type": "string",
      "description": "Its title.",
      "example": "The First"
    },
    "time": {
      "type": "number",
      "format": "double",
      "description": "Where it is, in seconds.",
      "example": 1830.0
    },
    "createdAt": {
      "type": "integer",
      "format": "int64",
      "description": "When it was made, in epoch milliseconds.",
      "example": 1763600000000
    }
  }
}

Status 400: The body is malformed. As text/plain, when the body is not syntactically valid JSON.

Failed to parse the request body as JSON: expected value at line 1 column 1

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item or bookmark.

Not Found

Schema:

A text/plain body: a string.

Status 413: The body is too long.

Payload Too Large

Schema:

A text/plain body: a string.

Status 415: The request did not declare a JSON body.

Expected request with `Content-Type: application/json`

Schema:

A text/plain body: a string.

Status 422: The JSON does not fit the body: a missing field, a wrong type or an unknown shape.

Failed to deserialize the JSON body into the target type: missing field `time` at line 1 column 2

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

DELETE /player/api/me/item/{id}/bookmark/{time}

Removes the bookmark at a time in an item.

Access: A player card's access token only (/player/login, /player/auth/refresh or the browser sign-in), from a signed-in, active patron; what the patron's scope hides answers 404.

Credentials: playerToken

Parameters

  • idpathstringrequiredItem id.
  • timepathstringrequiredThe bookmark's time in seconds.

Responses

  • 200OK. Body: string (text/plain)
  • 401No live player card (Unauthorized, plain text). Body: string (text/plain)
  • 403The patron must enroll a second factor on the library's website first (plain text). Body: string (text/plain)
  • 404No such item or bookmark. Body: string (text/plain)
  • 500The library could not be written. Body: string (text/plain)
  • 503The card could not be checked; retry (plain text). Body: string (text/plain)

Example request

$ curl 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>' \
    -X DELETE \
    -H 'Authorization: Bearer <playerToken>'
Invoke-RestMethod -Uri 'http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>' `
    -Method Delete `
    -Headers @{ Authorization = 'Bearer <playerToken>' }
import requests

response = requests.delete(
    "http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>",
    headers={"Authorization": "Bearer <playerToken>"},
)
print(response.status_code, response.text)
const response = await fetch("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>", {
  method: "DELETE",
  headers: { Authorization: "Bearer <playerToken>" },
});
console.log(response.status, await response.text());
let client = reqwest::Client::new();
let response = client
    .delete("http://127.0.0.1:8787/player/api/me/item/<id>/bookmark/<time>")
    .header("Authorization", "Bearer <playerToken>")
    .send()
    .await?;
println!("{} {}", response.status(), response.text().await?);

Example response

Status 200: OK.

string

Schema:

A text/plain body: a string.

Status 401: No live player card (Unauthorized, plain text).

Unauthorized

Schema:

A text/plain body: a string.

Status 403: The patron must enroll a second factor on the library's website first (plain text).

Enroll a second factor on the library's website first

Schema:

A text/plain body: a string.

Status 404: No such item or bookmark.

Not Found

Schema:

A text/plain body: a string.

Status 500: The library could not be written.

Internal Server Error

Schema:

A text/plain body: a string.

Status 503: The card could not be checked; retry (plain text).

Service Unavailable

Schema:

A text/plain body: a string.

Generated from crates/bookclerkd/openapi.json at main · View as Markdown