bookclerk_player_api::wire

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

Last updated View as Markdown

The response shapes player apps read.

Field names and types follow what apps written for an Audiobookshelf server parse: camelCase keys, lengths of time in seconds as JSON numbers (crate::time), times of day in milliseconds since the Unix epoch, and null (not an absent key) for an unknown value. Books are the only media type: no shape here carries a podcast field, because some apps tell a book from a podcast by which fields are present.

Items carry one metadata shape whether listed or fetched alone: the listing's flat names (authorName, seriesName) and the expanded arrays (authors, series) together, so an app reading either finds what it needs.

Item Kind Summary
Status struct GET /status: what an app asks before it signs in.
AuthFormData struct Text an app shows on its sign-in screen.
Ping struct GET /ping: { "success": true }.
LoginResponse struct The answer to a sign-in, a token refresh, POST /api/authorize and the browser sign-in's callback.
User struct A patron as apps see them.
Permissions struct What a patron may do, as apps read it.
ServerSettings struct The server settings apps read.
Libraries struct GET /api/libraries.
Library struct One library an app can open.
LibrarySettings struct A library's display settings.
LibraryWithFilterData struct GET /api/libraries/{id}?include=filterdata.
FilterData struct The values an app offers as filters.
NamedRef struct An id and a name.
SeriesRef struct A series an item belongs to, with the item's place in it.
ItemPage struct A page of items: GET /api/libraries/{id}/items and the like.
LibraryItem struct An item: an edition with a stored copy.
BookMedia struct A book's media: metadata, tracks and chapters.
BookMetadata struct A book's metadata.
LibraryFile struct A file of an item, in the expanded item's libraryFiles.
FileMetadata struct A file's name, size and times.
AudioFile struct An audio file of a book.
AudioTrack struct A track with its place in the book.
Chapter struct A chapter of a book.
MediaProgress struct The patron's progress on one item.
Bookmark struct A bookmark.
SessionDevice struct The device a playback session was opened from.
PlaybackSession struct A playback session, as POST /api/items/{id}/play answers.
SessionPage struct GET /api/me/listening-sessions.
ListeningStats struct GET /api/me/listening-stats.
ItemListening struct Seconds listened to one item.
LibraryItems struct { "libraryItems": [...] }: in-progress items and batch reads.
Series struct A series.
SeriesProgress struct The patron's progress through a series.
SeriesPage struct A page of series.
Author struct An author.
AuthorSeries struct A series of an author's, with the author's items in it.
Authors struct GET /api/libraries/{id}/authors without paging.
AuthorPage struct A page of authors.
Narrator struct A narrator with how many items they read.
Narrators struct GET /api/libraries/{id}/narrators.
Shelf struct A personalized shelf on the home screen.
SearchResults struct GET /api/libraries/{id}/search.
SearchBook struct An item that matched a search.
SearchSeries struct A series that matched a search.
LibraryStats struct GET /api/libraries/{id}/stats.
EmptyPage struct An empty page, for collections and playlists the library does not have yet.
Playlists struct { "playlists": [] }: the patron's playlists.
SyncResult struct One entry's outcome in a batch sync.
SyncResults struct POST /api/session/local-all.
ProgressEvent struct user_item_progress_updated on the socket: progress changed on another device.
SocketInit struct init on the socket: the socket is signed in.
SocketAuthFailed struct auth_failed on the socket.
MetaTags struct The tags read from an audio file, as apps read them: always empty until the stored media probe reads tags, so it serializes as {}.
ShelfEntities enum A shelf's entries.
title_ignore_prefix function The name an item's title sorts by: a leading The , A or An moved to the end (Hobbit, The), as apps show it in sorted lists.
last_first function A name family name first (Le Guin, Ursula K.): the last word moved to the front. A one-word name is returned as it is.
plain_text function Text with markup removed: everything between < and > dropped and the common entities decoded.
MEDIA_TYPE_BOOK constant The media type of every library and item the API lists.
STATUS_APP constant The app the status answer names. Apps check it before they offer a sign-in, so it is the value they expect.
AUTH_METHODS constant The sign-in methods an app may offer: a player password, and the browser sign-in through the library's own sign-in page.

Structs

Status

pub struct Status {
    pub app: &'static str,
    pub server_version: &'static str,
    pub is_init: bool,
    pub language: &'static str,
    pub auth_methods: Vec<&'static str>,
    pub auth_form_data: AuthFormData,
}

GET /status: what an app asks before it signs in.

Fields

  • app: Always STATUS_APP.
  • server_version: The server release whose API this one answers like (crate::COMPATIBLE_SERVER_VERSION).
  • is_init: Always true: the library is set up before an app can sign in.
  • language: The interface language apps show server text in.
  • auth_methods: AUTH_METHODS.
  • auth_form_data: What the sign-in screen shows.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

AuthFormData

pub struct AuthFormData {
    pub auth_login_custom_message: Option<String>,
    pub auth_openid_button_text: String,
    pub auth_openid_auto_launch: bool,
}

Text an app shows on its sign-in screen.

Fields

  • auth_login_custom_message: A note under the sign-in form: where to get a player password.
  • auth_openid_button_text: The label of the browser sign-in button.
  • auth_openid_auto_launch: Whether apps open the browser sign-in without a tap: never.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Ping

pub struct Ping {
    pub success: bool,
}

GET /ping: { "success": true }.

Fields

  • success: Always true.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LoginResponse

pub struct LoginResponse {
    pub user: User,
    pub user_default_library_id: String,
    pub server_settings: ServerSettings,
    pub ereader_devices: Vec<Value>,
    pub source: &'static str,
}

The answer to a sign-in, a token refresh, POST /api/authorize and the browser sign-in's callback.

Fields

  • user: The signed-in patron, with the card's tokens.
  • user_default_library_id: The library an app opens first: the whole library.
  • server_settings: Settings apps read at sign-in.
  • ereader_devices: E-reader devices: always empty, the API serves no ebooks.
  • source: How the server was installed; apps only display it.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

User

pub struct User {
    pub id: String,
    pub username: String,
    pub email: Option<String>,
    pub kind: &'static str,
    pub token: String,
    pub access_token: Option<String>,
    pub refresh_token: Option<String>,
    pub is_old_token: bool,
    pub media_progress: Vec<MediaProgress>,
    pub series_hide_from_continue_listening: Vec<String>,
    pub bookmarks: Vec<Bookmark>,
    pub is_active: bool,
    pub is_locked: bool,
    pub last_seen: Option<i64>,
    pub created_at: i64,
    pub permissions: Permissions,
    pub libraries_accessible: Vec<String>,
    pub item_tags_selected: Vec<String>,
    pub has_openid_link: bool,
}

A patron as apps see them.

Fields

  • id: The patron's portal identity id, as a string.
  • username: The name the patron signs in with.
  • email: The patron's email address, if the library has one.
  • kind: Always user: no app is given administrator powers.
  • token: The 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.
  • access_token: The card's access token, on sign-in and refresh answers only.
  • refresh_token: The card's refresh token, on sign-in and refresh answers only.
  • is_old_token: Always false: tokens are never the old non-expiring kind.
  • media_progress: Progress on every item the patron has started.
  • series_hide_from_continue_listening: Series hidden from continue listening: none.
  • bookmarks: Every bookmark the patron has made.
  • is_active: Always true: a disabled patron cannot sign in.
  • is_locked: Always false.
  • last_seen: When the patron was last seen, in epoch milliseconds.
  • created_at: When the patron joined, in epoch milliseconds.
  • permissions: What the patron may do.
  • libraries_accessible: Libraries the patron may open, by id.
  • item_tags_selected: Tags that limit what the patron sees: none (scope is applied by the host, not by tags).
  • has_openid_link: Whether the patron signed in through the browser at least once.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Permissions

pub struct Permissions {
    pub download: bool,
    pub update: bool,
    pub delete: bool,
    pub upload: bool,
    pub create_ereader: bool,
    pub access_all_libraries: bool,
    pub access_all_tags: bool,
    pub access_explicit_content: bool,
    pub selected_tags_not_accessible: bool,
}

What a patron may do, as apps read it.

Fields

  • download: Whether the patron may download items to the device.
  • update: Always false: apps edit nothing.
  • delete: Always false.
  • upload: Always false.
  • create_ereader: Always false.
  • access_all_libraries: Always true: the libraries listed are the ones the patron sees.
  • access_all_tags: Always true.
  • access_explicit_content: Always true: scope, not an explicit flag, decides visibility.
  • selected_tags_not_accessible: Always false.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

ServerSettings

pub struct ServerSettings {
    pub id: &'static str,
    pub version: &'static str,
    pub build_number: u32,
    pub language: &'static str,
    pub date_format: &'static str,
    pub time_format: &'static str,
    pub sorting_ignore_prefix: bool,
    pub sorting_prefixes: Vec<&'static str>,
    pub chromecast_enabled: bool,
    pub home_bookshelf_view: u8,
    pub bookshelf_view: u8,
    pub auth_active_auth_methods: Vec<&'static str>,
    pub auth_openid_button_text: String,
    pub auth_openid_auto_launch: bool,
    pub auth_login_custom_message: Option<String>,
    pub time_zone: String,
}

The server settings apps read.

Fields

  • id: Always server-settings.
  • version: [crate::COMPATIBLE_SERVER_VERSION]: apps turn features on by it.
  • build_number: Always 1.
  • language: The interface language.
  • date_format: How apps format dates.
  • time_format: How apps format times.
  • sorting_ignore_prefix: Whether sorting skips leading articles: no.
  • sorting_prefixes: The articles sorting would skip.
  • chromecast_enabled: Whether apps offer casting: no.
  • home_bookshelf_view: The home shelf style (1: standard).
  • bookshelf_view: The library shelf style (1: standard).
  • auth_active_auth_methods: AUTH_METHODS.
  • auth_openid_button_text: The browser sign-in button's label.
  • auth_openid_auto_launch: Never true.
  • auth_login_custom_message: The sign-in screen's note.
  • time_zone: The host's time zone name, or UTC.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Libraries

pub struct Libraries {
    pub libraries: Vec<Library>,
}

GET /api/libraries.

Fields

  • libraries: The libraries the patron may open.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Library

pub struct Library {
    pub id: String,
    pub name: String,
    pub folders: Vec<Value>,
    pub display_order: u32,
    pub icon: &'static str,
    pub media_type: &'static str,
    pub provider: &'static str,
    pub settings: LibrarySettings,
    pub last_scan: Option<i64>,
    pub last_scan_version: Option<String>,
    pub created_at: i64,
    pub last_update: i64,
}

One library an app can open.

Fields

  • id: The library id (crate::ids::WHOLE_LIBRARY_ID for the whole library).
  • name: The library's name.
  • folders: Folders on disk: none are shown.
  • display_order: The library's place in the list, from 1.
  • icon: The icon apps show (audiobookshelf names a book stack).
  • media_type: Always MEDIA_TYPE_BOOK.
  • provider: The metadata provider apps show: none.
  • settings: Display settings.
  • last_scan: Always null.
  • last_scan_version: Always null.
  • created_at: When the library was made, in epoch milliseconds.
  • last_update: When it last changed, in epoch milliseconds.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibrarySettings

pub struct LibrarySettings {
    pub cover_aspect_ratio: u8,
    pub disable_watcher: bool,
    pub audiobooks_only: bool,
    pub hide_single_book_series: bool,
    pub only_show_later_books_in_continue_series: bool,
    pub epubs_allow_scripted_content: bool,
    pub mark_as_finished_percent_complete: Option<f64>,
    pub mark_as_finished_time_remaining: f64,
}

A library's display settings.

Fields

  • cover_aspect_ratio: 1 for square covers, 2 for the 1.6:1 book shape: square.
  • disable_watcher: Always true: the library is not a watched folder.
  • audiobooks_only: Always true: audiobooks only.
  • hide_single_book_series: Whether one-book series are hidden from the series list: no.
  • only_show_later_books_in_continue_series: Whether continue series skips earlier books: no.
  • epubs_allow_scripted_content: Always false.
  • mark_as_finished_percent_complete: An item counts as finished at this share listened, in percent.
  • mark_as_finished_time_remaining: An item counts as finished with this many seconds left.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibraryWithFilterData

pub struct LibraryWithFilterData {
    pub filterdata: FilterData,
    pub issues: u64,
    pub num_user_playlists: u64,
    pub library: Library,
}

GET /api/libraries/{id}?include=filterdata.

Fields

  • filterdata: The filter values.
  • issues: Items with problems: none are reported.
  • num_user_playlists: The patron's playlists in the library: none.
  • library: The library.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

FilterData

pub struct FilterData {
    pub authors: Vec<NamedRef>,
    pub genres: Vec<String>,
    pub tags: Vec<String>,
    pub series: Vec<NamedRef>,
    pub narrators: Vec<String>,
    pub languages: Vec<String>,
    pub publishers: Vec<String>,
    pub published_decades: Vec<String>,
    pub book_count: u64,
    pub author_count: u64,
    pub series_count: u64,
    pub podcast_count: u64,
    pub number_episodes: u64,
    pub loaded_at: i64,
}

The values an app offers as filters.

Fields

  • authors: Authors with at least one item.
  • genres: Genres.
  • tags: Tags: none are shown.
  • series: Series with at least one item.
  • narrators: Narrators.
  • languages: Languages.
  • publishers: Publishers.
  • published_decades: Decades of publication: none are offered.
  • book_count: Items in the library.
  • author_count: Authors in the library.
  • series_count: Series in the library.
  • podcast_count: Always 0.
  • number_episodes: Always 0.
  • loaded_at: When the values were read, in epoch milliseconds.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

NamedRef

pub struct NamedRef {
    pub id: String,
    pub name: String,
}

An id and a name.

Fields

  • id: The entity's id.
  • name: Its display name.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SeriesRef

pub struct SeriesRef {
    pub id: String,
    pub name: String,
    pub sequence: Option<String>,
}

A series an item belongs to, with the item's place in it.

Fields

  • id: The series id.
  • name: The series name.
  • sequence: The item's place in the series as the library writes it (1, 2.5), if known.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

ItemPage

pub struct ItemPage {
    pub results: Vec<LibraryItem>,
    pub total: u64,
    pub limit: u64,
    pub page: u64,
    pub sort_by: Option<String>,
    pub sort_desc: bool,
    pub filter_by: Option<String>,
    pub media_type: &'static str,
    pub minified: bool,
    pub collapseseries: bool,
    pub include: String,
    pub offset: u64,
}

A page of items: GET /api/libraries/{id}/items and the like.

Fields

  • results: The page's items.
  • total: Items matching the query in all.
  • limit: Items per page (0: no paging).
  • page: The page number, from 0.
  • sort_by: The sort key the app sent, echoed.
  • sort_desc: Whether the order is reversed.
  • filter_by: The filter the app sent, echoed.
  • media_type: Always MEDIA_TYPE_BOOK.
  • minified: Whether items are minified.
  • collapseseries: Whether series were collapsed: never.
  • include: The include list the app sent, echoed.
  • offset: The offset of the first result.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibraryItem

pub struct LibraryItem {
    pub id: String,
    pub ino: String,
    pub old_library_item_id: Option<String>,
    pub library_id: String,
    pub folder_id: String,
    pub path: String,
    pub rel_path: String,
    pub is_file: bool,
    pub mtime_ms: i64,
    pub ctime_ms: i64,
    pub birthtime_ms: i64,
    pub added_at: i64,
    pub updated_at: i64,
    pub is_missing: bool,
    pub is_invalid: bool,
    pub media_type: &'static str,
    pub media: BookMedia,
    pub num_files: u64,
    pub size: u64,
    pub library_files: Option<Vec<LibraryFile>>,
    pub user_media_progress: Option<MediaProgress>,
    pub series_sequence: Option<String>,
}

An item: an edition with a stored copy.

Fields

  • id: The item id: the edition id.
  • ino: The item's inode as apps expect one: the edition id again.
  • old_library_item_id: Always null.
  • library_id: The library the item is listed in.
  • folder_id: The folder id: the library id.
  • path: A display path: the title.
  • rel_path: A display path: the title.
  • is_file: Always false: an item is a folder of tracks.
  • mtime_ms: When the copy last changed, in epoch milliseconds.
  • ctime_ms: When the copy was stored, in epoch milliseconds.
  • birthtime_ms: When the copy was stored, in epoch milliseconds.
  • added_at: When the item joined the library, in epoch milliseconds.
  • updated_at: When its record last changed, in epoch milliseconds.
  • is_missing: Always false.
  • is_invalid: Always false.
  • media_type: Always MEDIA_TYPE_BOOK.
  • media: The book.
  • num_files: Files in the item.
  • size: Bytes in all its files.
  • library_files: The item's files, when the item is fetched expanded.
  • user_media_progress: The patron's progress, when the app asked for it.
  • series_sequence: The item's place in a series, on a series' book list.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

BookMedia

pub struct BookMedia {
    pub id: String,
    pub library_item_id: Option<String>,
    pub metadata: BookMetadata,
    pub cover_path: Option<String>,
    pub tags: Vec<String>,
    pub num_tracks: u64,
    pub num_audio_files: u64,
    pub num_chapters: u64,
    pub duration: f64,
    pub size: u64,
    pub audio_files: Option<Vec<AudioFile>>,
    pub chapters: Option<Vec<Chapter>>,
    pub tracks: Option<Vec<AudioTrack>>,
}

A book's media: metadata, tracks and chapters.

Fields

  • id: The media id: the edition id.
  • library_item_id: The item id, when fetched expanded.
  • metadata: The book's metadata.
  • cover_path: A cover path apps only test for presence; covers are fetched from /api/items/{id}/cover.
  • tags: Tags: none.
  • num_tracks: Tracks in play order.
  • num_audio_files: Audio files.
  • num_chapters: Chapters.
  • duration: The book's length in seconds.
  • size: Bytes in its audio files.
  • audio_files: The audio files, when fetched expanded.
  • chapters: The chapters, when fetched expanded.
  • tracks: The tracks with their place in the book, when fetched expanded.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

BookMetadata

pub struct BookMetadata {
    pub title: String,
    pub title_ignore_prefix: String,
    pub subtitle: Option<String>,
    pub authors: Vec<NamedRef>,
    pub author_name: String,
    pub author_name_lf: String,
    pub narrators: Vec<String>,
    pub narrator_name: String,
    pub series: Vec<SeriesRef>,
    pub series_name: String,
    pub genres: Vec<String>,
    pub published_year: Option<String>,
    pub published_date: Option<String>,
    pub publisher: Option<String>,
    pub description: Option<String>,
    pub description_plain: Option<String>,
    pub isbn: Option<String>,
    pub asin: Option<String>,
    pub language: Option<String>,
    pub explicit: bool,
    pub abridged: bool,
}

A book's metadata.

Fields

  • title: The title.
  • title_ignore_prefix: The title for sorting.
  • subtitle: The subtitle, if any.
  • authors: The authors.
  • author_name: The authors' names joined with , .
  • author_name_lf: The authors' names, family name first, joined with , .
  • narrators: The narrators' names.
  • narrator_name: The narrators' names joined with , .
  • series: The series the book is in.
  • series_name: The series names with the book's place (Name #2), joined.
  • genres: Genres.
  • published_year: The year of publication, as a string ("2019").
  • published_date: The date of publication, if known.
  • publisher: The publisher.
  • description: The description, as the library stores it.
  • description_plain: The description with markup removed.
  • isbn: The ISBN, if known.
  • asin: The ASIN, if known.
  • language: The language.
  • explicit: Always false.
  • abridged: Whether the edition is abridged.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibraryFile

pub struct LibraryFile {
    pub ino: String,
    pub metadata: FileMetadata,
    pub added_at: i64,
    pub updated_at: i64,
    pub file_type: &'static str,
}

A file of an item, in the expanded item's libraryFiles.

Fields

  • ino: The file's ino (crate::ids::file_ino).
  • metadata: The file's name, size and times.
  • added_at: When the file was stored, in epoch milliseconds.
  • updated_at: When the file was stored, in epoch milliseconds.
  • file_type: Always audio.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

FileMetadata

pub struct FileMetadata {
    pub filename: String,
    pub ext: String,
    pub path: String,
    pub rel_path: String,
    pub size: u64,
    pub mtime_ms: i64,
    pub ctime_ms: i64,
    pub birthtime_ms: i64,
}

A file's name, size and times.

Fields

  • filename: The file name.
  • ext: The extension with its dot (.m4b).
  • path: A display path: the file name.
  • rel_path: A display path: the file name.
  • size: The file's size in bytes.
  • mtime_ms: When the file was stored, in epoch milliseconds.
  • ctime_ms: When the file was stored, in epoch milliseconds.
  • birthtime_ms: When the file was stored, in epoch milliseconds.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

AudioFile

pub struct AudioFile {
    pub index: u64,
    pub ino: String,
    pub metadata: FileMetadata,
    pub added_at: i64,
    pub updated_at: i64,
    pub track_num_from_meta: Option<u64>,
    pub disc_num_from_meta: Option<u64>,
    pub track_num_from_filename: Option<u64>,
    pub disc_num_from_filename: Option<u64>,
    pub manually_verified: bool,
    pub exclude: bool,
    pub error: Option<String>,
    pub format: Option<String>,
    pub duration: f64,
    pub bit_rate: Option<u64>,
    pub language: Option<String>,
    pub codec: Option<String>,
    pub time_base: Option<String>,
    pub channels: Option<u64>,
    pub channel_layout: Option<String>,
    pub chapters: Vec<Chapter>,
    pub embedded_cover_art: Option<String>,
    pub meta_tags: MetaTags,
    pub mime_type: String,
}

An audio file of a book.

Fields

  • index: The file's place in play order, from 1.
  • ino: The file's ino (crate::ids::file_ino).
  • metadata: The file's name, size and times.
  • added_at: When the file was stored, in epoch milliseconds.
  • updated_at: When the file was stored, in epoch milliseconds.
  • track_num_from_meta: The track number the file's tags state: not read.
  • disc_num_from_meta: The disc number the file's tags state: not read.
  • track_num_from_filename: The track number in the file name: not read.
  • disc_num_from_filename: The disc number in the file name: not read.
  • manually_verified: Always false.
  • exclude: Always false.
  • error: Always null.
  • format: The container format, such as mp4 or mp3.
  • duration: The file's length in seconds.
  • bit_rate: Bits per second, if known.
  • language: The file's language, if known.
  • codec: The codec, if known.
  • time_base: The time base, if known.
  • channels: Audio channels, if known.
  • channel_layout: The channel layout, if known.
  • chapters: Chapters embedded in the file: none are read.
  • embedded_cover_art: Always null.
  • meta_tags: Tags read from the file: none until the stored media probe reads them.
  • mime_type: The file's media type, such as audio/mp4.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

AudioTrack

pub struct AudioTrack {
    pub index: u64,
    pub start_offset: f64,
    pub duration: f64,
    pub title: String,
    pub content_url: String,
    pub mime_type: String,
    pub codec: Option<String>,
    pub metadata: Option<FileMetadata>,
}

A track with its place in the book.

Fields

  • index: The track's place in play order, from 1.
  • start_offset: Where the track starts in the book, in seconds.
  • duration: The track's length in seconds.
  • title: The track's title: its file name.
  • content_url: The path the track streams from, under the API's base address (/api/items/{id}/file/{ino}); apps add ?token=.
  • mime_type: The track's media type.
  • codec: The codec, if known.
  • metadata: The file's name, size and times.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Chapter

pub struct Chapter {
    pub id: u64,
    pub start: f64,
    pub end: f64,
    pub title: String,
}

A chapter of a book.

Fields

  • id: The chapter's place, from 0.
  • start: Where it starts, in seconds.
  • end: Where it ends, in seconds.
  • title: Its title.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

MediaProgress

pub struct MediaProgress {
    pub id: String,
    pub user_id: String,
    pub library_item_id: String,
    pub episode_id: Option<String>,
    pub media_item_id: String,
    pub media_item_type: &'static str,
    pub duration: f64,
    pub progress: f64,
    pub current_time: f64,
    pub is_finished: bool,
    pub hide_from_continue_listening: bool,
    pub ebook_location: Option<String>,
    pub ebook_progress: Option<f64>,
    pub last_update: i64,
    pub started_at: i64,
    pub finished_at: Option<i64>,
}

The patron's progress on one item.

Fields

  • id: The progress id: the item id (one record per patron and item).
  • user_id: The patron's id.
  • library_item_id: The item id.
  • episode_id: Always null.
  • media_item_id: The media id: the item id.
  • media_item_type: Always book.
  • duration: The book's length in seconds, as last reported.
  • progress: The share listened, from 0 to 1.
  • current_time: Where the patron is, in seconds.
  • is_finished: Whether the patron finished it.
  • hide_from_continue_listening: Whether it is hidden from continue listening.
  • ebook_location: Always null.
  • ebook_progress: Always null.
  • last_update: When the progress last changed, in epoch milliseconds.
  • started_at: When the patron started, in epoch milliseconds.
  • finished_at: When the patron finished, in epoch milliseconds.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Bookmark

pub struct Bookmark {
    pub library_item_id: String,
    pub title: String,
    pub time: f64,
    pub created_at: i64,
}

A bookmark.

Fields

  • library_item_id: The item it is in.
  • title: Its title.
  • time: Where it is, in seconds.
  • created_at: When it was made, in epoch milliseconds.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SessionDevice

pub struct SessionDevice {
    pub device_id: String,
    pub device_name: Option<String>,
    pub client_name: Option<String>,
}

The device a playback session was opened from.

Fields

  • device_id: The device's id: the card's session id.
  • device_name: The device name the app reported, if any.
  • client_name: The app's name, if reported.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

PlaybackSession

pub struct PlaybackSession {
    pub id: String,
    pub user_id: String,
    pub library_id: String,
    pub library_item_id: String,
    pub book_id: String,
    pub episode_id: Option<String>,
    pub media_type: &'static str,
    pub media_metadata: BookMetadata,
    pub chapters: Vec<Chapter>,
    pub display_title: String,
    pub display_author: String,
    pub cover_path: Option<String>,
    pub duration: f64,
    pub play_method: u8,
    pub media_player: String,
    pub device_info: SessionDevice,
    pub server_version: &'static str,
    pub date: String,
    pub day_of_week: String,
    pub time_listening: f64,
    pub start_time: f64,
    pub current_time: f64,
    pub started_at: i64,
    pub updated_at: i64,
    pub audio_tracks: Vec<AudioTrack>,
    pub library_item: Option<LibraryItem>,
}

A playback session, as POST /api/items/{id}/play answers.

Fields

  • id: The session id; apps send it back to sync and close.
  • user_id: The patron's id.
  • library_id: The library id.
  • library_item_id: The item id.
  • book_id: The media id: the item id.
  • episode_id: Always null.
  • media_type: Always MEDIA_TYPE_BOOK.
  • media_metadata: The book's metadata.
  • chapters: The book's chapters.
  • display_title: The title apps show.
  • display_author: The author apps show.
  • cover_path: A cover path apps test for presence.
  • duration: The book's length in seconds.
  • play_method: How the app plays: 0, direct play of the stored files.
  • media_player: The player the app reported.
  • device_info: The device the session was opened from.
  • server_version: crate::COMPATIBLE_SERVER_VERSION.
  • date: The day the session started, YYYY-MM-DD in UTC.
  • day_of_week: The weekday the session started, in English.
  • time_listening: Seconds listened in this session.
  • start_time: Where the session started, in seconds.
  • current_time: Where the patron is, in seconds.
  • started_at: When the session started, in epoch milliseconds.
  • updated_at: When it last synced, in epoch milliseconds.
  • audio_tracks: The tracks to play, in order.
  • library_item: The item, expanded.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SessionPage

pub struct SessionPage {
    pub total: u64,
    pub num_pages: u64,
    pub page: u64,
    pub items_per_page: u64,
    pub sessions: Vec<PlaybackSession>,
}

GET /api/me/listening-sessions.

Fields

  • total: Sessions in all.
  • num_pages: Pages in all.
  • page: The page number, from 0.
  • items_per_page: Sessions per page.
  • sessions: The page's sessions, newest first.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

ListeningStats

pub struct ListeningStats {
    pub total_time: f64,
    pub items: BTreeMap<String, ItemListening>,
    pub days: BTreeMap<String, f64>,
    pub day_of_week: BTreeMap<String, f64>,
    pub today: f64,
    pub recent_sessions: Vec<PlaybackSession>,
}

GET /api/me/listening-stats.

Fields

  • total_time: Seconds listened in all.
  • items: Seconds listened per item, by item id.
  • days: Seconds listened per day, by YYYY-MM-DD.
  • day_of_week: Seconds listened per weekday, by English weekday name.
  • today: Seconds listened today.
  • recent_sessions: The most recent sessions.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

ItemListening

pub struct ItemListening {
    pub id: String,
    pub time_listening: f64,
    pub media_metadata: BookMetadata,
}

Seconds listened to one item.

Fields

  • id: The item id.
  • time_listening: Seconds listened.
  • media_metadata: The item's metadata.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibraryItems

pub struct LibraryItems {
    pub library_items: Vec<LibraryItem>,
}

{ "libraryItems": [...] }: in-progress items and batch reads.

Fields

  • library_items: The items.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Series

pub struct Series {
    pub id: String,
    pub name: String,
    pub name_ignore_prefix: String,
    pub description: Option<String>,
    pub added_at: i64,
    pub updated_at: i64,
    pub library_id: String,
    pub books: Option<Vec<LibraryItem>>,
    pub progress: Option<SeriesProgress>,
}

A series.

Fields

  • id: The series id.
  • name: Its name.
  • name_ignore_prefix: The name for sorting.
  • description: Its description: none.
  • added_at: When the library first saw it, in epoch milliseconds.
  • updated_at: When it last changed, in epoch milliseconds.
  • library_id: The library it is listed in.
  • books: Its items in series order, on lists.
  • progress: The patron's progress through it, when asked for.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SeriesProgress

pub struct SeriesProgress {
    pub library_item_ids: Vec<String>,
    pub library_item_ids_finished: Vec<String>,
    pub is_finished: bool,
}

The patron's progress through a series.

Fields

  • library_item_ids: The series' items, by id.
  • library_item_ids_finished: Those the patron finished.
  • is_finished: Whether the patron finished every one.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SeriesPage

pub struct SeriesPage {
    pub results: Vec<Series>,
    pub total: u64,
    pub limit: u64,
    pub page: u64,
    pub sort_by: Option<String>,
    pub sort_desc: bool,
    pub filter_by: Option<String>,
    pub minified: bool,
    pub include: String,
}

A page of series.

Fields

  • results: The page's series.
  • total: Series in all.
  • limit: Series per page.
  • page: The page number, from 0.
  • sort_by: The sort key, echoed.
  • sort_desc: Whether the order is reversed.
  • filter_by: The filter, echoed.
  • minified: Whether items are minified.
  • include: The include list, echoed.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Author

pub struct Author {
    pub id: String,
    pub asin: Option<String>,
    pub name: String,
    pub last_first: String,
    pub description: Option<String>,
    pub image_path: Option<String>,
    pub library_id: String,
    pub added_at: i64,
    pub updated_at: i64,
    pub num_books: u64,
    pub library_items: Option<Vec<LibraryItem>>,
    pub series: Option<Vec<AuthorSeries>>,
}

An author.

Fields

  • id: The contributor id.
  • asin: Always null.
  • name: The author's name.
  • last_first: The name family name first.
  • description: Always null.
  • image_path: Always null: no author images.
  • library_id: The library it is listed in.
  • added_at: When the library first saw the author, in epoch milliseconds.
  • updated_at: When the record last changed, in epoch milliseconds.
  • num_books: Items by the author the patron can see.
  • library_items: The author's items, when asked for.
  • series: The author's series with their items, when asked for.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

AuthorSeries

pub struct AuthorSeries {
    pub id: String,
    pub name: String,
    pub items: Vec<LibraryItem>,
}

A series of an author's, with the author's items in it.

Fields

  • id: The series id.
  • name: The series name.
  • items: The items, in series order.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Authors

pub struct Authors {
    pub authors: Vec<Author>,
}

GET /api/libraries/{id}/authors without paging.

Fields

  • authors: The authors.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

AuthorPage

pub struct AuthorPage {
    pub results: Vec<Author>,
    pub total: u64,
    pub limit: u64,
    pub page: u64,
}

A page of authors.

Fields

  • results: The page's authors.
  • total: Authors in all.
  • limit: Authors per page.
  • page: The page number, from 0.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Narrator

pub struct Narrator {
    pub id: String,
    pub name: String,
    pub num_books: u64,
}

A narrator with how many items they read.

Fields

  • id: The name in URL-safe base64, as apps filter by it.
  • name: The narrator's name.
  • num_books: Items they read that the patron can see.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Narrators

pub struct Narrators {
    pub narrators: Vec<Narrator>,
}

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

Fields

  • narrators: The narrators.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Shelf

pub struct Shelf {
    pub id: &'static str,
    pub label: &'static str,
    pub label_string_key: &'static str,
    pub kind: &'static str,
    pub entities: ShelfEntities,
    pub total: u64,
}

A personalized shelf on the home screen.

Fields

  • id: The shelf id, such as continue-listening.
  • label: The shelf's English label.
  • label_string_key: The key apps translate the label by.
  • kind: What the shelf holds: book, series or authors.
  • entities: The shelf's entries.
  • total: Entries in all.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SearchResults

pub struct SearchResults {
    pub book: Vec<SearchBook>,
    pub podcast: Vec<Value>,
    pub narrators: Vec<Narrator>,
    pub tags: Vec<Value>,
    pub genres: Vec<Value>,
    pub series: Vec<SearchSeries>,
    pub authors: Vec<Author>,
}

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

Fields

  • book: Matching items.
  • podcast: Always empty.
  • narrators: Matching narrators.
  • tags: Always empty.
  • genres: Always empty.
  • series: Matching series.
  • authors: Matching authors.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SearchBook

pub struct SearchBook {
    pub library_item: LibraryItem,
}

An item that matched a search.

Fields

  • library_item: The item.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SearchSeries

pub struct SearchSeries {
    pub series: Series,
    pub books: Vec<LibraryItem>,
}

A series that matched a search.

Fields

  • series: The series.
  • books: Its items.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

LibraryStats

pub struct LibraryStats {
    pub total_items: u64,
    pub total_authors: u64,
    pub total_genres: u64,
    pub total_duration: f64,
    pub num_audio_tracks: u64,
    pub total_size: u64,
}

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

Fields

  • total_items: Items.
  • total_authors: Authors.
  • total_genres: Genres.
  • total_duration: Seconds of audio in all.
  • num_audio_tracks: Audio tracks in all.
  • total_size: Bytes in all: not counted.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

EmptyPage

pub struct EmptyPage {
    pub results: Vec<Value>,
    pub total: u64,
    pub limit: u64,
    pub page: u64,
}

An empty page, for collections and playlists the library does not have yet.

Fields

  • results: Always empty.
  • total: Always 0.
  • limit: Items per page, echoed.
  • page: The page number, echoed.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Playlists

pub struct Playlists {
    pub playlists: Vec<Value>,
}

{ "playlists": [] }: the patron's playlists.

Fields

  • playlists: Always empty.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SyncResult

pub struct SyncResult {
    pub id: String,
    pub success: bool,
    pub error: Option<String>,
}

One entry's outcome in a batch sync.

Fields

  • id: The session or item id the entry named.
  • success: Whether it was applied.
  • error: Why not, when it was not.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SyncResults

pub struct SyncResults {
    pub results: Vec<SyncResult>,
}

POST /api/session/local-all.

Fields

  • results: One outcome per entry, in the order sent.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

ProgressEvent

pub struct ProgressEvent {
    pub id: String,
    pub session_id: Option<String>,
    pub device_description: String,
    pub data: MediaProgress,
}

user_item_progress_updated on the socket: progress changed on another device.

Fields

  • id: The progress id.
  • session_id: The session that changed it, if one did.
  • device_description: The device that changed it.
  • data: The progress.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SocketInit

pub struct SocketInit {
    pub user_id: String,
    pub username: String,
}

init on the socket: the socket is signed in.

Fields

  • user_id: The patron's id.
  • username: The patron's sign-in name.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

SocketAuthFailed

pub struct SocketAuthFailed {
    pub message: &'static str,
}

auth_failed on the socket.

Fields

  • message: Why, in English.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

MetaTags

pub struct MetaTags {}

The tags read from an audio file, as apps read them: always empty until the stored media probe reads tags, so it serializes as {}.

Implements: Clone, ComposeSchema, Debug, Default, Serialize, ToSchema

Enums

ShelfEntities

pub enum ShelfEntities {
    Books(Vec<LibraryItem>),
    Series(Vec<Series>),
    Authors(Vec<Author>),
}

A shelf's entries.

Variants

  • Books: Items.
  • Series: Series.
  • Authors: Authors.

Implements: Clone, ComposeSchema, Debug, Serialize, ToSchema

Functions

title_ignore_prefix

pub fn title_ignore_prefix(title: &str) -> String

The name an item's title sorts by: a leading The , A or An moved to the end (Hobbit, The), as apps show it in sorted lists.

last_first

pub fn last_first(name: &str) -> String

A name family name first (Le Guin, Ursula K.): the last word moved to the front. A one-word name is returned as it is.

plain_text

pub fn plain_text(html: &str) -> String

Text with markup removed: everything between < and > dropped and the common entities decoded.

Constants

MEDIA_TYPE_BOOK

pub const MEDIA_TYPE_BOOK: &str = "book";

The media type of every library and item the API lists.

STATUS_APP

pub const STATUS_APP: &str = "audiobookshelf";

The app the status answer names. Apps check it before they offer a sign-in, so it is the value they expect.

AUTH_METHODS

pub const AUTH_METHODS: [&str; 2] = _;

The sign-in methods an app may offer: a player password, and the browser sign-in through the library's own sign-in page.

Generated from crates/bookclerk-player-api at main · View as Markdown