External Media

Self-hosted only. Nostos can read audiobooks and ebooks from a folder you already keep on the server, without copying them. You scan the folder, review what was found, import it, and scan again later when you add more.

Your original files stay where they are and are never modified or deleted by Nostos.

Nostos Cloud does not have this feature.

Set it up

The web interface cannot choose a folder. Whoever runs the server makes one folder visible to Nostos, once. Settings → External media is always there on a self-hosted server and shows these steps until a folder is available.

Step 1: give Nostos the folder

Docker Compose

Add one line under volumes for the nostos service. The Compose file in the Nostos repository has it ready to uncomment.

services:
  nostos:
    image: ghcr.io/christian-gennari/nostos:latest
    ports:
      - "5099:8080"
    volumes:
      - nostos-data:/data
      - /mnt/audiobooks:/external/media:ro      # add this line
    restart: unless-stopped

volumes:
  nostos-data:

• Replace /mnt/audiobooks with the folder on your machine. Keep /external/media exactly as written: that is where the Nostos image looks.
• :ro mounts the folder read-only. Nostos never writes to it, and with :ro the operating system would refuse even if it tried.
• Keep the nostos-data:/data line. Nostos stores its database, notes, covers and backups there and needs to write to it.

Apply it:

docker compose up -d

docker run

Add one -v to the command you already use:

docker run -d \
  --name nostos \
  -p 5099:8080 \
  -v nostos-data:/data \
  -v /mnt/audiobooks:/external/media:ro \
  --restart unless-stopped \
  ghcr.io/christian-gennari/nostos:latest

A running container cannot be given a new folder. Remove it (docker rm -f nostos) and run the command again; your library is in the nostos-data volume and is kept.

Without Docker

There is no default folder outside the Docker image. Set the environment variable ExternalMedia__Root (two underscores) to the absolute path of the folder, or add this to appsettings.json, and restart Nostos:

{
  "ExternalMedia": { "Root": "/mnt/audiobooks" }
}

In Docker the same setting changes where the image looks, if you would rather mount the folder somewhere other than /external/media.

Step 2: let Nostos read the files (Linux)

The container runs as a user that is not root (user id 1654). That user must be able to read the files and open the folders:

chmod -R o+rX /mnt/audiobooks

This changes permissions only. It does not change the files.

Step 3: check it worked

Open Nostos and go to Settings → External media. It should say Available. Press Scan folder.

What you see	What it means	What to do
The setup steps instead of a linked folder	Nothing is mounted where Nostos looks	Docker: check the volume line ends in :/external/media:ro and that you ran docker compose up -d, not only a restart. Without Docker: set ExternalMedia__Root
Not available	The folder was there before and has gone away	Mount it again. Linked books keep their notes and progress meanwhile
The server does not start	ExternalMedia__Root is not an absolute path	Use a path that starts with /. The log says ExternalMedia:Root must be an absolute path
The scan finds 0 books and says folders could not be read	The server’s user is not allowed to read the folder	Run the chmod command in step 2
The scan finds 0 books and no folders were skipped	There is nothing Nostos can link in the folder	Check the mounted folder is the right one and see How the folder is read
No External media entry in Settings	The server is older than this feature, or it is Nostos Cloud	Update the image: docker compose pull && docker compose up -d

To see the folder the way Nostos sees it:

docker exec nostos ls /external/media

One folder

This release links one folder. To link several, mount them side by side below it:

    volumes:
      - /mnt/audiobooks:/external/media/audiobooks:ro
      - /mnt/ebooks:/external/media/ebooks:ro

If you later mount the same folder at a different path, linked books keep working as long as the files are at the same place below it. Books follow the folder’s identity (ExternalMedia__RootId, default external), not its path. Leave that setting alone once you have linked books.

How the folder is read

In the folder	Becomes
An .epub or .pdf file	One ebook
An .m4b file	One audiobook
A folder with one .mp3 or .m4a file	One audiobook
A folder with several .mp3 or .m4a files	One audiobook with one track per file

A layout like this works well:

audiobooks/
  Ursula K. Le Guin/
    A Wizard of Earthsea/
      01 - Warriors in the Mist.mp3
      02 - The Shadow.mp3
      cover.jpg
  Bram Stoker/
    Dracula.m4b
ebooks/
  Middlemarch.epub

• Track order is the file name order, with numbers read as numbers, so 2 - Intro comes before 10 - End.
• Title and author come from the file’s own tags, then from the file or folder name. Nostos does not guess an author from a folder higher up.
• Covers come from cover.jpg, cover.png or folder.jpg in a track folder, or from artwork embedded in the audio file. Nostos stores its own copy of the cover. EPUB and PDF covers are not read yet.
• Symbolic links and hidden files (names starting with a dot) are skipped and never followed.
• Other audio and ebook formats (FLAC, OGG, MOBI and others) cannot be linked yet. They are counted on the review screen and left alone.

Books that need a decision

Some layouts can be read two ways. These are shown under Check these and are left out unless you tick them:

• a book with the same title and author as one already in your library (it is added as a separate book, never merged);
• audio files in a folder that also holds an .m4b;
• several audio files directly in the linked folder;
• disc folders such as CD 1 and CD 2 (each is proposed as its own book);
• a folder with its own audio files and subfolders that also hold audio.

A book cannot be imported when its file cannot be read, when a folder holds more than 2,000 tracks, or when new files appear in a folder that is already a linked book. For the last case, remove the book from Nostos and import the folder again.

Scan, review, import

1. Scan folder. Nostos lists the folder and reads tags. Nothing is added.
2. Review and import. Untick anything you do not want. Tick the books under Check these that you do want.
3. Import. The import runs on the server. You can close the window or the page; reopening Settings shows the progress.

Importing reads each audio track once to measure it. No media file is copied or converted. A large library takes time to read, and nothing else.

Importing twice is safe. A file belongs to one book only, so a book that is already linked is reported as such and nothing is duplicated.

Scan again

Run Scan again after you add files. New books appear as ready. Nostos does not watch the folder and does not scan on a schedule.

Removing a linked book

Remove from Nostos deletes the book, its notes and its reading progress from Nostos, and the cover Nostos stored. The original files are not touched. Scan again and the book is offered for import once more.

Uploading a file to a linked book stores that file in Nostos and stops using the linked one. The original is not replaced.

When files go missing

If a file is moved, renamed or deleted, or the folder is not mounted:

• the book stays in your library with its notes and progress;
• its page shows External file unavailable;
• the next scan lists it under Files no longer in the folder.

Put the file back at the same place and the book works again. Nostos never removes a book because its file disappeared. A renamed file is seen as a new book, so the old entry has to be removed by hand.

Backups and moving your library

	What it contains for a linked book
Backup (Settings → Backups & data)	The book, its notes, its progress, and the reference to the file. Not the media.
Portable export (.nostos)	Everything, including the media itself.

• Restoring a backup brings linked books back as linked books. They play once the same folder is mounted again. Back up the media folder yourself.
• A portable export reads every linked file into the archive, so it can be as large as the linked library. The Nostos it is imported into stores those files itself and needs no folder. Server paths are never written into the archive.
• If a linked file cannot be read during an export, the export stops with an error instead of producing an archive that lacks it. Mount the folder, or remove the book, and export again.

Streaming and offline listening

Linked books are streamed from the server like any other book. Nostos does not download them to a phone for offline listening.