mirror of
https://github.com/wrolpi/wrolpi-help.git
synced 2026-10-26 19:01:40 -04:00
217ff68098
Also: adding WROLPi Portable (Live USB) to Getting Started, syncing the Home TOC with all existing pages, pointing eBooks/PDFs at the Docs module, recommending Raspberry Pi Imager instead of Etcher, and fixing typos. Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
91 lines
4.8 KiB
Markdown
91 lines
4.8 KiB
Markdown
# How WROLPi Stores Files
|
|
|
|
Everything in your WROLPi library is a plain file in the [media directory](special-directories.md) — videos, web
|
|
page archives, ebooks, Zims, maps. The database is only an index of those files: it can be deleted and rebuilt at
|
|
any time from the files on disk and your [configs](configs.md). There is no hidden storage format; you can browse
|
|
your entire library with any file manager, on any computer.
|
|
|
|
## FileGroups
|
|
|
|
WROLPi groups related files together into a **FileGroup**: files in the *same directory* that share the same name
|
|
(stem) are treated as one item in your library.
|
|
|
|
For example, these four files are one FileGroup, displayed as a single video:
|
|
|
|
```
|
|
videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.mp4 <- the video (primary file)
|
|
videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.info.json <- metadata
|
|
videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.en.vtt <- captions
|
|
videos/WROLPi/WROLPi_20230909_0xfMLNVFq2Y_WROLPi demo.jpg <- poster
|
|
```
|
|
|
|
WROLPi understands multi-part suffixes like `.info.json`, `.readability.html`, `.readability.txt`, and
|
|
per-language caption suffixes like `.en.vtt` — they all group with their base file.
|
|
|
|
Typical FileGroups:
|
|
|
|
| Kind | Files |
|
|
|---|---|
|
|
| [Video](../modules/videos/files.md) | `.mp4` + `.info.json` + captions (`.vtt`/`.srt`) + poster image |
|
|
| [Archive](../modules/archives/files.md) | SingleFile `.html` + `.readability.html`/`.txt`/`.json` + screenshot |
|
|
| eBook | `.epub` or `.mobi` + a cover image |
|
|
| Document | a single `.pdf`, `.docx`, comic book, etc. |
|
|
|
|
### The primary file
|
|
|
|
Each FileGroup has a **primary file** which decides how the group appears and behaves in the interface. When a group
|
|
contains several file types, WROLPi picks the most important one: an archive page, video, or audio file beats an
|
|
ebook, an ebook beats a PDF, and images are only primary when nothing else is present. A Video, Archive, or eBook
|
|
record is then attached to the FileGroup based on the primary file's type.
|
|
|
|
Files that share a stem but live in **different directories are not grouped** — a FileGroup never spans directories.
|
|
|
|
## The File Refresh
|
|
|
|
The refresh is how WROLPi discovers your files. It scans the media directory, groups files into FileGroups, indexes
|
|
their contents for search, and creates the Video/Archive/eBook records.
|
|
|
|
> To refresh all your files, click the **Files** link in the top navigation bar, then click **Refresh** at the
|
|
> bottom of the files table. You can also select specific files or directories and refresh only those.
|
|
|
|
Things to know about the refresh:
|
|
|
|
* A brand-new WROLPi has an empty library until the first full refresh completes — the Dashboard will remind you.
|
|
* Videos and other downloads refresh their own directories automatically when they complete.
|
|
* The refresh refuses to run if the media directory looks empty — this protects your database when a drive failed to
|
|
mount.
|
|
* A full refresh of a large library can take a long time; progress is displayed while it runs.
|
|
|
|
## Indexing and Search
|
|
|
|
During the refresh, WROLPi extracts searchable text from your files. What is extracted depends on the file type:
|
|
|
|
* **Videos**: the title, description, and the full caption/subtitle text.
|
|
* **Archives**: the page title and the readability article text.
|
|
* **eBooks / PDFs / documents**: the title, author, and the document text.
|
|
* **Everything else**: at minimum, the words of the file name.
|
|
|
|
Search offers two modes: the default **fast search** matches titles and other important fields, while **deep
|
|
search** also matches the full body text (captions, article contents, document text).
|
|
|
|
## The Database Can Be Rebuilt
|
|
|
|
Because the database is derived, deleting it is not a disaster:
|
|
|
|
* FileGroups, Videos, Archives, and eBooks are rebuilt by a file refresh.
|
|
* Everything you curated — [Tags](tags.md), Channels, Playlists, Downloads, settings — is restored from your
|
|
[configs](configs.md).
|
|
* Only minor runtime data is lost, such as video watch history.
|
|
|
|
## Rules to Know
|
|
|
|
* All files must live inside the media directory (`/media/wrolpi/`). WROLPi cannot see files outside it.
|
|
* **Use the [Files module's tools](../modules/files/index.md) to move, rename, or delete files.** The tools keep the
|
|
database and your Tags in sync. If you move or rename a tagged file outside of WROLPi, the Tag can be lost because
|
|
Tags are keyed by the file's path.
|
|
* You can add files yourself (over the network, or by plugging the drive into another computer): put them anywhere
|
|
in the media directory, keep sidecar files (posters, captions, metadata) next to their base file with the same
|
|
stem, then run a refresh.
|
|
* Directories can be **ignored** from the Files module if you do not want their contents indexed or searchable.
|
|
* Never store your own files in the `tags` or `config` directories — see
|
|
[Special Directories](special-directories.md).
|