Media library

Where libraries appear

Libraries appear in the app's Media interface as "CloudDrive Libraries", next to Emby and Jellyfin servers. Choose Media under Settings → Interface to start the app on the poster wall.

• Home: Featured, Continue Watching, Next Up, Continue Listening, Continue Reading, and a "Latest" row for each library. A library being scanned or synced shows its state, such as Scanning, Identifying or Syncing; one that another device scans shows Elsewhere or Waiting (see One device scans a library).
• Featured: a carousel at the top of Home with titles from Continue Watching, Next Up and the newest in each library. Titles of a locked private library, and titles above parental control's rating limit while locked, are never featured.
• Search: translated and alternative titles are found too, and accents and Traditional or Simplified Chinese don't matter. A song is found once its album's page has been opened.
• Favorites: kept apart from library data, so Clear library data and a rescan keep them, and they sync with Sync libraries across devices.

Devices

The CloudDrive2 apps on iPhone, iPad, Mac, Windows PCs, Apple TV, Apple Vision Pro, Android phones, tablets and TVs, and Meta Quest. Each device builds its libraries itself; no server has to stay on.

The features are the same on every device, with these differences: the Emby API isn't on Meta Quest; Apple TV can't import from Emby or Jellyfin, but shows libraries another device imported; on Apple TV and Android TV, person pages leave out the links and Scan again has no custom interval; on Apple TV, Edit metadata… changes text only, and on Android TV its pictures come only from your cloud storage; Android has no video-track picker, and no picking several titles or right-click menu. Smaller differences are noted where they matter.

The core service's web interface doesn't show libraries. It has a Titles to Confirm page where you can confirm, in a browser, the titles the automatic match wasn't sure about. See Confirming on the web.

App Pro

The whole media library needs App Pro: adding and editing libraries, online info, identifying titles, saving info and artwork, syncing across devices, and browsing and playing in the Media interface.

How to import

1. Sign in to the server under Media Servers first. Only a server administrator can read the libraries' folders.
2. In Settings → Media Libraries, choose Import from Emby or Jellyfin…, then the server.
3. The server's libraries are listed with each of their folders. A folder on this device's cloud storage shows "… plays directly from …"; one that isn't (the server's own disk or NAS) shows "… is not on this device's cloud storage" and is left out. The matching cloud folder comes from the CloudDrive2 companion plugin on the server, the same storage account, and the path mappings you set for the server under Media Servers.
4. Tick the libraries, choose which people to import and which goes first when CloudDrive already has something, and choose Import. It runs in the background: you can close the window, and Settings → Media Libraries shows how far it has got. A library imported before shows Update; importing it again brings it up to date.

The server's movie libraries become film libraries, its TV libraries show libraries, and its other video libraries mixed libraries. Music and book libraries can't be imported yet.

When CloudDrive already has it

Chosen separately for titles and for people: The server's first (titles' default), CloudDrive's first, or Whichever has it; the newer when both do (people's default). An empty field never replaces a filled one, and nothing of CloudDrive's is deleted. Importing the same server again starts from the last choices; a library's title choice can also be changed in its editor, on the "Imported from …" row, without reading the server again.

What comes along

• Films' and shows' names, original titles, plots, taglines, genres, tags, studios, age ratings, ratings and premiere dates; posters, logos, banners, thumbs and every backdrop, fetched from the server when shown.
• A show's seasons and episodes, each episode's name, plot, numbers, runtime and air date.
• The media info the server read: resolution, HDR and Dolby Vision, audio tracks (Atmos and DTS:X included) and subtitles. Files the server couldn't read, some ISOs for example, are detected by the app in the background.
• Your played state, resume points and favourites on the server (the signed-in user's); a newer one on the device is kept.
• People: People in these libraries with a biography or photo (the default), Everyone in these libraries, Everyone on the server, or No one. Their biographies, birth and death dates, birthplaces, photos and up to six backdrops, their tags and one-line description. Photos are downloaded to the device.

After the import

• An imported library is read from the server: no folder is scanned and nothing is looked up online, and Home and the library page show "Reading from <server> · N titles read". Each rescan reads the server again, and titles the server no longer lists leave.
• With Sync libraries across devices and Sync scanned data on, an imported library reaches your other devices, which use what the importing device read; people's biographies, photos and first three backdrops travel too. On a device not signed in to that server, a server picture that can't load gives way to another.
• Apple TV doesn't import, but shows the libraries another device imported.

The NFO and artwork you have

NFO files, posters, backdrops, logos and season posters written by Kodi, Emby, Jellyfin, tinyMediaManager and similar tools are read. When an NFO has a TMDB or IMDb id, the entry is fetched by that id and nothing is searched.

The NFO and artwork in the folder come first, and TMDB fills only what they leave out; with the library's Prefer online info on, it is the other way round. What you save with Edit metadata… always comes first.

What comes from TMDB

Title, plot, genres, rating, poster and backdrop, cast and directors, each season and episode, box sets, and the certifications used by parental control. The language they show in is the library's Metadata language.

Anime

Anime named the fansub way is looked up on Bangumi first, and the bangumi-data table gives the TMDB season and episode it maps to, so anime whose seasons TMDB divides differently still lands on the right episode.

Identify…

Every title page has Identify…: pick one of up to 5 candidates, search by title and year, mark it Not on TMDB, or Look Up Automatically. When the identification is an automatic match, Keep This Match makes it your choice.

Your choice stays, and automatic matching never overwrites it; with sync on, your other devices take it too. Identify… works even with the library's Look up online off.

Identify Album and Identify Book

Identify Album on an album page and Identify Book on a book page pick the right MusicBrainz or Open Library entry, which fills in a missing year and cover. The choice syncs with the library.

AI identification

For films, albums and books the rules can't identify, an AI model can suggest what to search for. Under Settings → Media Libraries → Identification → AI identification, choose the service, the model and the API key (the same key AI subtitles use), and the libraries the model reads. Private libraries and libraries with Look up online off can't be chosen.

• The model reads an item's path below its library folder and what was read from its files, and gives search terms only. TMDB, MusicBrainz and Open Library are then searched as usual, and the rules above decide.
• Once on, the model is asked in the background about items not identified yet. Each item's answer is kept on the device; at most 1,000 calls a day.
• Ask AI in Identify… shows the model's answer and its evidence. Nothing is saved until you pick a result.

Confirming on the web

The core service's web interface has a Titles to Confirm page, handy for clearing in a computer's browser the titles a TV has piled up.

• At least one device needs Sync libraries across devices on. The page reads the review lists your devices upload to the CloudDrive2 Sync folder.
• Pick a candidate, or paste a TMDB link or ID; the page has no title search.
• Your devices take the choice the next time they sync.
• Titles of a private library show after you unlock with the PIN.

Default shelves

Until you edit them, a library uses the default shelves, named in the app's language. A Mixed library has both the film and the show shelves, films first.

movie:
  Animation:
    genre_ids: '16'
  Chinese-language:
    original_language: 'zh,cn,bo,za'
  Other languages:
tv:
  Chinese animation:
    genre_ids: '16'
    origin_country: 'CN,TW,HK'
  Anime:
    genre_ids: '16'
    origin_country: 'JP'
  Documentary:
    genre_ids: '99'
  Kids:
    genre_ids: '10762'
  Variety:
    genre_ids: '10764,10767'
  Chinese drama:
    origin_country: 'CN,TW,HK'
  Western drama:
    origin_country: 'US,FR,GB,DE,ES,IT,NL,PT,RU,UK'
  Asian drama:
    origin_country: 'JP,KP,KR,TH,IN,SG'
  Other:

Conditions

• Separate several values with ,, ， or 、; any one of them is enough.
• A shelf outside movie: and tv: is for both films and shows.
• Up to 100 shelves, names up to 40 characters. The editor points out problems line by line; Restore defaults brings the default shelves back, and turning off Use shelves removes them.
• The facts come from the NFO first, then TMDB. Without an original language, it is taken from the country (mainland China, Taiwan and Singapore are Chinese; Hong Kong and Macau Cantonese). With Look up online off, only NFO facts are used.
• A title whose facts aren't known yet is on no shelf for now, but it is in All.
• Shelves don't show while browsing by folder. Music and book libraries have no shelves.
• A library with box sets also has Collections at the end of its shelf row.

Person pages

• Cast and directors: biography, photo and links from TMDB, in the library's metadata language; the page lists the titles in your libraries that name them.
• Artists: biography and photo from Wikipedia and Wikimedia Commons, through the links MusicBrainz gives.
• Authors: a biography from Open Library and Wikipedia.
• One person is one record whether an NFO, TMDB or a music or book credit names them, and any of their names finds them.
• Names, biographies and photos other apps send through the Emby API come first.

Box sets

TMDB's collection, or the NFO's <set>, puts a film in a box set. Box sets with at least two films in the library appear under Collections in the shelf row.

Edit metadata

Film and show pages have Edit metadata… for the title, plot, genres, cast, pictures and more. Edits are saved as the NFO file and pictures in the film's folder, so other apps and your other devices read them too; only what you changed is rewritten, and what other apps wrote stays. Your edits outrank online info, and Prefer online info never replaces them. Apple TV can't change pictures.

Options

• Copies for Infuse: also writes the poster and backdrop under the names Infuse reads (<file name>.jpg, <file name>-fanart.jpg).
• Actor photos (.actors folder): up to 20 cast photos in each title's .actors folder.
• Check again: checks every identified title again. Files that exist are never replaced.

NFO files use Kodi's format, in the device's display language: title, original title, rating, plot, tagline, runtime, TMDB and IMDb ids, genres, directors, premiere date, cast and more, with <lockdata> so Emby and Jellyfin don't rewrite them. A file whose media info was detected also gets its video, audio and subtitle tracks. movie.nfo and logos are not written.

An album gets files only when MusicBrainz has decided it and it has a folder of its own; no cover is written when the folder already has any picture. A book gets files only when Open Library has decided it. Music libraries need Look up music on MusicBrainz, and book libraries Look up books on Open Library.

Other people's files are left alone

• An NFO written by CloudDrive2 carries a marker on its second line. If a folder already has another tool's NFO, nothing is written for that title. If it already has a poster, backdrop or other image in a role, that image is skipped.
• The exception: in a video library with both Prefer online info and Save info and artwork beside the media on, after a confirmation, other apps' .nfo files and pictures are renamed (with .bak added) and replaced with TMDB's. Nothing is deleted. Music and book libraries have no such exception.
• When a title's identity changes, only files CloudDrive2 wrote itself, and nobody changed since, are replaced.
• A file you delete isn't written again unless you choose Check again.
• For a private library, a warning comes first: titles, plot and posters are saved as ordinary files that anyone who can open the folders, and the storage provider, can see. Nothing is written while it is locked.

How fast

Before it starts, you see an estimate: about 3 files per film, 3 per show plus 2 per episode, and 2 more with Infuse copies. Files are uploaded one at a time, at least 1 second apart. When the storage asks to slow down, writing continues 15 minutes later.

Formats

EPUB, MOBI, AZW, AZW3, PRC and CBZ open in the book reader, PDF in the PDF viewer, TXT in the text viewer. When a book has several formats, EPUB opens first; the others open from the book's page.

What the files say

Calibre's metadata.opf (including what plugins such as Douban fetched), the title, authors, description and cover inside EPUB, MOBI and AZW3 files, and a CBZ comic's ComicInfo.xml. Only the parts needed are read; whole books are never downloaded. Junk values such as "Unknown", and advertising such as WeChat accounts, are ignored.

Covers

A picture with the book's name or Calibre's cover.jpg, then a picture in the folder, then the cover inside the book, then Open Library. With none, a cover with the title and author is drawn.

Reading and Open Library

• Home shows the books you are reading first. Reading positions can sync across devices with progress sync.
• With Look up books on Open Library and the library's Look up online both on, books missing a year or a cover are looked up, by ISBN first, then by title and author. Open Library has little on Chinese books.
• Identify Book on the book page picks an Open Library book by hand; see Identify Album and Identify Book. An author's page shows a biography from Open Library and Wikipedia.

What syncs

• Each library's settings, including its folders, recognition words, shelves and the device that scans it; deleting a library syncs too.
• The PIN check (not the PIN itself).
• The identifications of titles, albums and books, your choices included.
• Favorites, and each season's intro and ending times.
• The Needs review list, for the web page.

What doesn't

• Library data and pictures: these sync with Sync scanned data across devices, a switch of its own.
• Choices for this device only, such as the online info switches, Listing speed, Picture limit and parental control.
• Watch progress and watched marks: these sync with progress sync.

Folder layout

CloudDrive2 Sync/
  README.txt
  <CloudDrive account>/
    progress/   progress sync
    library/    media libraries
      Living Room TV.<device id>.<seq>.json
      MacBook.<device id>.<seq>.json

Each device writes only its own file, and every file holds everything that device has merged, so any one file gives a new device the full set of libraries.

How changes merge

Each setting merges on its own, and the latest change wins; your choice always outranks an automatic match. A deleted library never comes back. Files written by a newer version of the app are skipped, with a prompt to update.

When it syncs

A device reads when the app starts, comes back to the front, or opens a library, and uploads a change within seconds. When the storage limits requests, it waits at least 15 minutes before trying again. On storage with a recycle bin, replaced files go to the bin; see storage differences.

• Lock Again: 5 minutes after you leave the app by default, or when you leave it, or after 15 minutes or 1 hour. The app starts locked every time.
• A private library starts with Look up online off, and its titles are never sent to the AI identification service.
• Where another library's folders overlap a private library, the overlapping part is hidden there too while locked.
• Forgot PIN…: the PIN can't be recovered. You can remove every private library and the PIN, then add them again; their folders and files stay.

Settings

• Port: 29801 by default. On iPhone, iPad and Apple Vision Pro it runs only while the app is on the screen.
• This device only: only apps on this device can connect; when off, apps on your local network can.
• API keys: make one for each app that connects, and choose the libraries it reaches. Private libraries are reached only when "Private libraries too" was chosen after unlocking with the PIN.
• In MoviePilot, choose Emby as the server type, then enter the address and a key.

What other apps write

• People's names, biographies, photos and roles, and Favorites. People's details show before what the NFO and TMDB say.
• It is kept on this device, never in your media's folders; Clear library data and rescans keep it.
• With Sync scanned data across devices on, it travels to your other devices with the photos.
• Only people's details and Favorites are taken for now; a title's own details and pictures are not.