Organising your library

How to name and arrange your films, television, music, music videos and home videos so Home Stream recognises every one of them.

The short version

Each kind of media has its own folder. Films go in one folder, television in another, and so on. The server's administrator adds them in Settings → Library Folders → Add a Folder, choosing an existing folder with Browse or making one there with New Folder. When a drive fills up, add a second folder of the same kind on another drive.
Name films Title (Year), give episodes S01E01, and file music as artist folder, then album folder, then tracks.
If your library is already set up for Plex or Jellyfin, it works as it is.
If you copy files onto the drive yourself, run Settings → Library Maintenance → Library Scan afterwards. Or use Schedule Scans on the same page to check on a timer. Anything you upload appears straight away.

A scan never moves, renames or changes your files. It only reads them. If a file goes missing, for example because a drive didn't mount, the server notes it and keeps its entry until the file comes back. The few things that do change files are listed at the bottom of this page, and you start every one of them yourself.

Films

Home Stream finds a video at any depth inside your films folder. A film can sit loose beside others or in a folder of its own, and both can be mixed in one library.

Films/
  Big Buck Bunny (2008).mp4
  Sintel (2010).mkv
  Harbour Lights (2019)/
    Harbour Lights (2019).mkv
    The Lighthouse-deleted.mkv
    Featurettes/
      Building the Pier.mkv

Years

Put the year in round or square brackets after the title, for example Sintel (2010).mkv. Dots and underscores count as spaces. A film without a year still appears, but it's harder to match, because the year is what tells a remake from the original.

Loose, or in a folder of its own

A loose film is fine until you want more than one special feature of the same kind. A folder of its own allows as many as you like. To count as the film's own folder, the folder must have exactly the same name as the film's file, minus the extension, like Harbour Lights (2019)/Harbour Lights (2019).mkv.

Films matched before

If a file or folder name already contains a TMDb id, like {tmdb-603}, the server uses it to match exactly. It also uses an .nfo or .plexmatch file beside the film. Without any of these, it searches by the title and year in the name.

The title you see comes from the match, not from the file name. When you correct a match, the file is renamed to agree. See the bottom of this page.

Television

Give each series a folder of its own, and inside it a folder for each season.

Television/
  The Lighthouse Keepers/
    Season 1/
      The Lighthouse Keepers - S01E01 - Arrival.mkv
      The Lighthouse Keepers - S01E02 - The Storm.mkv
    Season 2/
      The Lighthouse Keepers - S02E01 - Return.mkv
    Specials/
      The Lighthouse Keepers - S00E01 - Christmas.mkv

Season folders

Season 1, Season 01, Series 1 and S1 all work, as do the words for "season" in several other languages, such as Staffel 1 or Saison 1.
A folder called Specials is season 0, and it's shown as Specials.
Episodes can also sit loose in the series folder. They're grouped by the season in their names (S02E05 goes in season 2). If a name doesn't say, the episode goes in season 1.
A folder whose name gives no season number is read as season 1. That's why special features need one of the folder names listed under Special features.

Episode numbers

S01E01, in capitals or small letters, is the most reliable form. E01, Episode 1 and a leading 01 - also work. A file with no number at all is numbered by its place in the folder, so it's worth avoiding. Episode titles come from the match, so the title in a file name only matters until then.

Two episodes in one file

Files named like S01E01-E02, S01E01E02 or S01E01-02 are recorded as the first episode only. The scan result and the library problems banner both say so. The fix is to split the file in two. Each half then gets its own title, resume position and watched mark.

Music

Music is two folders deep: the artist, then the album, with the tracks directly inside the album folder.

Music/
  The Harbour Band/
    Low Tide/
      01 - Low Tide.flac
      02 - Fog Horn.flac
  Various Artists/
    Songs of the Sea/
      01 - Shanty.mp3

Tags come first

A track's title, number and disc come from the tags inside the file. The file name is only used when a tag is missing. The artist and album come from the folder names, and a tag never overrides them. When a track's own artist differs from the album's, as on a compilation, the track's artist comes from its tags. Home Stream never writes to your tags.

Tags are read when a file is first found. To re-read them across music already in your library, use Settings → Library Maintenance → Re-read Music Tags. Nothing on the drive changes.

Albums on more than one disc

One folder: the disc number comes from the tags, or from names like 1-01 Title and 2-03 Title. Names like 101 and 201 also work, but only when every numbered file in the folder has three digits and more than one disc is present.
A folder per disc, side by side: folders ending in Disc 1, Disc 2 (or Disk, or CD) become one album. This only happens when another folder for the same album is there, so a lone Disc 2 keeps its own name.
Not read: disc folders inside an album folder, like Low Tide/Disc 1/. Tracks there aren't found at all.

Music videos

Music videos can go in a folder of their own, or beside the songs in an album folder.

Music Videos/
  The Harbour Band/
    Low Tide (2019)-video.mp4
    Live at the Pier (2021)-concert.mkv
    Low Tide/
      Fog Horn (2019)-lyrics.mp4
    Interviews/
      Talking Tides.mp4
  The Harbour Band - Sea Shanty.mp4

Music/
  The Harbour Band/
    Low Tide/
      01 - Low Tide.flac
      Low Tide-video.mp4

The kind

The kind goes at the end of the name, after a hyphen: -video, -live, -lyrics, -concert, -interview, -behindthescenes or -documentary. Spaces around the hyphen are fine (Low Tide - live.mp4). -featurette is read as behind the scenes, and -clip and -short as videos. A name that gives no kind is a video.

A folder can give the kind instead: Videos, Clips, Concerts, Interviews, Behind The Scenes, Featurettes or Documentaries. Live and Lyrics aren't read as kinds, because both are ordinary album names.

Year, title and artist

The year goes in brackets before the kind: Low Tide (2019)-video.mp4.
For MP4, M4V and MOV files, the title and year in the file's own tags take priority over the name.
The artist comes from the folder. A video at the top of the music videos folder takes its artist from the name (Artist - Title) or from its tags.
A video goes with the album whose songs it sits beside, or the album folder it's in. A video named after one song's file (the song's file name, then - and the title) belongs to that song.

Special features

Trailers, deleted scenes, featurettes and the like are attached to the film or series they belong to. They don't show up as titles of their own. You can mark one with a suffix on its name or by putting it in a named folder. Capitals and spaces don't matter.

-trailer or a Trailers folder
-behindthescenes or Behind The Scenes
-deleted or Deleted Scenes
-featurette or Featurettes
-interview or Interviews
-scene or Scenes
-short or Shorts
-other or Other

For films

Beside a loose film: name the feature exactly after the film's file, plus a suffix, like Harbour Lights (2019)-trailer.mkv. That allows one of each kind.
In a film's own folder: give each feature its own name plus a suffix, like The Lighthouse-deleted.mkv, or put it in one of the folders above. Have as many as you like.

For television

A named folder inside the series folder holds features for the whole show. One inside a season folder holds features for that season.
A suffixed file loose in a series or season folder works too. It won't be mistaken for an episode.

Stick to the names above. A folder called Extras, for example, isn't one of them. Inside a series it's read as a season, and a video in an unrecognised folder inside your films folder is read as a film.

Trailers you keep as files

If a film's own trailer is in your library (Film (Year)-trailer.mkv, or in a Trailers folder in the film's folder), the Trailer button plays it instead of an online trailer. If there are several, the longest plays. The trailer settings only control online trailers. A trailer you keep is treated like any other special feature, and anyone allowed to watch the film can watch it.

Editions

A director's cut, a colourised print or a version with a commentary can sit beside the film it belongs to and appear as one title with a choice of version. Mark each version with an {edition-…} tag at the end of its name.

Films/
  Harbour Lights (2019).mkv
  Harbour Lights (2019) {edition-Director's Cut}.mkv
  Harbour Lights (2019) {edition-Black and White}.mkv

Versions must be in the same folder, with names identical apart from the tag. Nothing may come after the closing brace except the extension.
The untagged file plays by default. To change which version plays, choose Play by Default on that version's menu. Rename changes what a version is called in Home Stream without touching the file.
If every version is tagged, the first in alphabetical order becomes the main title.
Episodes can be tagged the same way, for example S05E12 - Title {edition-Commentary}.mkv.
Your watched mark is shared by every version. Your place in the film is kept separately for each version.

Only the tag makes a version. Two copies of a film side by side without a tag, such as a 1080p and a 4K copy, appear as two separate films.

What plays

Home Stream doesn't convert anything. Each device plays the file exactly as it is, so a file that device can't open won't play on it.

Some formats can't be opened by the browser or by the iPhone and iPad apps. The server marks those files as unable to play and says why:

AVI, WMV, ASF, FLV, RealMedia, DivX, VOB and MPEG (.mpg, .mpeg) files
Video encoded as Windows Media (including VC-1), early Microsoft MPEG-4, RealVideo or old Flash video, whatever file it's in

The fix is to convert the file to MP4, with H.264 video. When the video inside is already H.264, repackaging it as MP4 is enough and nothing needs re-encoding.

Disc images (.iso) aren't read. After each scan, the server tells you how many files it skipped because it doesn't read their format, and which formats they were.

Only formats that fail everywhere are marked. A file that plays on one device but not another isn't marked.

Coming from Plex or Jellyfin

A library laid out for either works as it is:

Films named Title (Year), loose or in folders of their own
Season and Specials folders
Special-feature suffixes and folders
{edition-…} tags
TMDb ids in names, .nfo files and .plexmatch files
Music videos in either app's layout

Some folders belong to other programs and are skipped, including Plex's optimised Plex Versions, the bookkeeping folders a NAS writes and the system's recycle bins. Hidden files and folders, whose names start with a dot, are skipped too.

Three things aren't read:

Disc folders inside an album folder
Versions that Jellyfin groups by putting them in one folder. Each file appears as a film of its own unless it carries an {edition-…} tag.
An artist named only in a music video's .nfo file

Home videos

Home videos are switched off until you turn them on in Settings → Server → Home Videos. Then the administrator adds a home videos folder in Settings → Library Folders → Add a Folder. Home videos are kept apart from everything else, and child accounts can't see them.

Home Videos/
  1994/
    1994-12-25 Christmas morning.mp4
  2024/
    2024-08-10 Road trip.mp4
  Undated/
    Grandad's garden.mp4

Uploads are filed for you like this, by year, with the title and date you give.
A scan also takes in videos already anywhere in the folder. A date at the start of the name (1994-12-25, 1994_12_25 or 1994.12.25) is the date, and the rest of the name is the title. Without one, the date the camera wrote into the file is used. If there's neither, the video is undated.
A scan only adds home videos. It never moves, renames or deletes one, and it doesn't drop a video whose file has gone missing.
More formats are accepted here, including DV, 3GP, AVCHD, VOB and MPEG. A video that won't play is kept and marked, so you can convert it.

When Home Stream does change your files

Each of these is something you do on purpose. None of them ever replaces a file that's already there. If the new name is taken, the file is left as it was.

Correcting a film's match. Fix Metadata, Refresh Metadata or uploading a film renames its file to Title (Year).ext, so it agrees with the match. Its other versions move with it and keep their tags. Ids are never written into a name.
Correcting a music video's kind or year. Its file name is updated, because that's where both are kept.
Editing a home video's title or date. The file moves to its new place in the dated folders.
Adding a second special feature of one kind to a loose film. The film, its versions and its features move into a folder of their own.
Deleting. The files move to the Trash. See Uploading and deleting.

All documentation · Next: Matching and metadata