wrolpi-help/docs/system/filegroups.md

How WROLPi Stores Files

Everything in your WROLPi library is a plain file in the media directory — 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. 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	.mp4 + .info.json + captions (.vtt/.srt) + poster image
Archive	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, Channels, Playlists, Downloads, settings — is restored from your configs.
• 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 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.