Documentation
Server
Configuration

Configuration

The Takeout server has a configuration file and each media directory has a configuration file. The configuration file formats are parsed using Viper so formats like JSON, TOML and YAML can be used. YAML is used in most examples unless stated otherwise.

This page is intended to be a reference and document most of the configuration options.

Server

The default server configuration file is called takeout.yaml. This can be changed with the –config command-line option.

Below is an example configuration file with the default values for reference.

# takeout.yaml
Server:
  Listen: 127.0.0.1:3000
  DataDir: .
  MediaDir: .
  ClientIPHeader: ""
  ImageClient:
    CacheDir: imagecache
    MaxAge: 720h
  IncludeDirs: []
  ExcludeDirs: [/bin/, /boot/, /dev/, /etc/, /lib/, /proc/, /run/, /sbin/, /root/, /sys/]

Auth:
  SecureCookies: true
  SessionAge: 720h
  AccessToken:
    Issuer: takeout
    Secret: "some secret phrase"
    Age: 4h
  MediaToken:
    Issuer: takeout
    SecretFile: "use a file instead of phrase"
    Age: 8766h
  FileToken:
    Issuer: takeout
    Secret: "some secret phrase"
    Age: 1h
  CodeToken:
    Issuer: takeout
    Secret: "some secret phrase"
    Age: 5m
  PasswordEntropy: 60
  DB:
    Driver: sqlite3
    Source: auth.db
    Logger: default

Progress:
  DB:
    Driver: sqlite3
    Source: progress.db
    Logger: default

Activity:
  DB:
    Driver: sqlite3
    Source: activity.db
    Logger: default

Favorite:
  DB:
    Driver: sqlite3
    Source: favorite.db
    Logger: default
Name Description
Server.Listen Address and port to listen on (default 127.0.0.1:3000)
Server.DataDir Directory for the server databases
Server.MediaDir Directory with a sub-directory for each media configuration
Server.ClientIPHeader Header with the real client address when behind a proxy, such as X-Real-IP. Used for login throttling. Leave empty when not behind a proxy.
Server.ImageClient Image cache directory and age (default 720h = 30 days)
Server.IncludeDirs Local file paths allowed to be served (default is all)
Server.ExcludeDirs Local file paths never served (default is common system directories)
Auth.SecureCookies Only send cookies over TLS (default true)
Auth.SessionAge How long a login session lasts (default 720h = 30 days)
Auth.PasswordEntropy Minimum password entropy in bits (default 60)

Each token (Access, Media, File, Code) has an Issuer, an Age, and a Secret or SecretFile. A secret must be assigned for each token. See security for details.

Database

The server configuration includes 4 databases:

  • activity
  • auth
  • favorite
  • progress

Each is configured using the fields in the table below.

Name Description
Driver Use “sqlite3”, it’s super fast and builtin
Source Name of database file
Logger Use debug, default or discard

mysql was tested and worked in the past.

Name Description
Driver mysql
Source takeout:takeout@tcp(127.0.0.1:3306)/mydb

Activity

Name Description
TrackLimit How many track listens to consider (default 9999)
MovieLimit How many movie views to consider (default 999)
TopArtistsLimit How many top artists (default 999)
TopReleasesLimit How many top releases (default 999)
TopTracksLimit How many top tracks (default 9999)
TopMoviesLimit How many top movies (default 999)
RecentTracksTitle Title for recent tracks (default “Recently Played”)
RecentMoviesTitle Title for recent movies (default “Recently Watched”)
TopArtistsTitle Title for top artists (default “Top Artists”)
TopReleasesTitle Title for top releases (default “Top Releases”)
TopTracksTitle Title for top tracks (default “Top Tracks”)
TopMoviesTitle Title for top movies (default “Top Movies”)

Favorite

Users can mark artists, tracks, movies and TV shows as favorites.

Name Description
ArtistLimit How many favorite artists (default 999)
ArtistsTracksLimit How many tracks per artist in the favorite artists playlist (default 50)
TrackLimit How many favorite tracks (default 9999)
MovieLimit How many favorite movies (default 999)
TVSeriesLimit How many favorite TV shows (default 999)

Media

Each media directory has a config.yaml. A general template for this configuration file would be:

Buckets:
  # bucket config

Music:
  # music config

Film:
  # film config

TV:
  # tv config

Podcast:
  # podcast config

Client:
  # client config

# api keys

Buckets

Media is stored in buckets which can be S3 buckets or a locally accessible directory. Each media bucket needs a type (music, film, tv) to let the server know how to parse the media objects.

The below example has two S3 buckets with music and films, and a local directory with TV shows.

Buckets:
  - Media: music
    S3:
      Endpoint: https://s3.us-west-1.example.com
      Region: us-west-1
      AccessKeyID: ##########
      SecretAccessKey: ##########
      BucketName: mybucket
      ObjectPrefix: Music
      URLExpiration: 15m
    RewriteRules:
      - Pattern: "^(.+/)Billy F Gibbons(/Hardware.+/.+)$"
        Replace: "$1Billy Gibbons$2"
      - Pattern: "^(.+/)Dr. Octagon(/Dr. Octagon, Part II.+/.+)$"
        Replace: "$1Kool Keith$2"
      - Pattern: "^(.+/White Zombie/La Sexorcisto_ Devil Music, )Volume One(.+/.+)$"
        Replace: "$1Vol. 1$2"
  - Media: film
    S3:
      Endpoint: https://s3.us-west-1.example.com
      Region: us-west-1
      AccessKeyID: ##########
      SecretAccessKey: ##########
      BucketName: mybucket
      ObjectPrefix: Movies
      URLExpiration: 15m
  - Media: tv
    FS:
      Root: /data/video/tvshows

Important

The S3 Endpoint must include the scheme, https:// (or http:// for a local Minio server without TLS). UseSSL is no longer used.

Music

Name Description
ArtistFile Used to help find artists MBID
ArtistRadioBreadth How many similar artists to use (default 10)
ArtistRadioDepth How many similar artists tracks to include (default 3)
TrackRadioBreadth How many similar artists to use for track radio (default 10)
TrackRadioDepth How many tracks per artist for track radio (default 5)
DeepLimit How many deep tracks (default 50)
PopularLimit How many popular tracks (default 50)
RadioGenres List of genres for stations (default from artist genres)
RadioLimit How many radio tracks (default 25)
RadioOther List of names and queries for custom stations
RadioSearchLimit How many tracks to search for radio (default 1000)
RadioSeries List of MusicBrainz series names for stations
RadioStreams Define Internet radio streams (see below)
Recent How recent is recent (default 8760h = 1 year)
RecentLimit How many recent (default 50)
RelatedArtists Time range for related artists (default 43800h = +/- 5 years)
ReleaseCountries Preferred release countries (default US, XW, XE)
ReleaseFormats Preferred release formats (default CD, Digital Media)
SearchLimit How many items to return (default 100)
SimilarArtistsLimit How many similar artists (default 10)
SimilarReleases Duration for similar (default 8760h = 1 year)
SimilarReleasesLimit How many similar releases (default 10)
SinglesLimit How many singles (default 50)
SyncInterval How often to automatically resync media from buckets (1h)
PopularSyncInterval How often to resync popular tracks (24h)
SimilarSyncInterval How often to resync similar artists (24h)
CoverSyncInterval How often to cache cover images (24h)

ReleaseFormats are in order of preference. The default prefers a CD release over a Digital Media release when both are available in MusicBrainz.

Artists File

When you run into trouble matching artist names to MusicBrainz artists, this file can save the day. You’ll need this when there are artists with the same name and you want a specific one, artists with ambiguous names or for some reason or another Takeout just can’t figure it out. Create an artist file like this:

{
    "Belly" : "c118bc97-11a7-41dc-a55e-48c3bcf22ac2",
    "POW!" : "e00ac97d-3ed1-4f3e-86e1-1b15dd3ad6ad",
    "Phoenix" : "8d455809-96b3-4bb6-8829-ea4beb580d35",
    "Isao Tomita" : "9119e57f-1086-48b2-8a93-57feacb7f6d9",
    "Organisation _ Kraftwerk" : "7b6de1a2-d119-48a6-a17c-5472df12beeb",
    "Kid Rock & The Twisted Brown Trucker" : "ad0ecd8b-805e-406e-82cb-5b00c3a3a29e",
    "R.E.M_" : "ea4dfa26-f633-4da6-a52a-f49ea4897b58",
    "Gary Numan & Ade Fenton" : "6cb79cb2-9087-44d4-828b-5c6fdff2c957",
    "Sonic Youth, I.C.P. & The Ex" : "5cbef01b-cc35-4f52-af7b-d0df0c4f61b9",
    "The Vines" : "4e045c96-538b-46ed-8ea8-7cae20b56574",
    "CHVRCHΞS" : "6a93afbb-257f-4166-b389-9f2a1e5c5df8"
}

Internet Radio

A few examples are included in the builtin configuration. Add your own as follows:

Music:
  RadioStreams:
    - Creator: "SomaFM"
      Title: "Groove Salad"
      Description: "A nicely chilled plate of ambient/downtempo beats and grooves."
      Image: "https://somafm.com/img3/groovesalad-400.jpg"
      Source:
        - ContentType: "audio/aac"
          URL: "https://somafm.com/groovesalad130.pls"
    - Creator: "SomaFM"
      Title: "Indie Pop Rocks"
      Image: "https://somafm.com/img3/indiepop-400.jpg"
      Source:
        - ContentType: "audio/aac"
          URL: "https://somafm.com/indiepop130.pls"

Note

Streams that only have http:// URLs may not play in the web UI when the server uses https.

Film 

Film:
  Recent: "8760h"
  RecentLimit: 50
  SearchLimit: 100
  SyncInterval: "1h"
Name Description
CastLimit How many cast members (default 25)
CrewJobs Crew jobs to index (default director, executive producer, novel, producer, screenplay, story)
DuplicateResolution Which file to keep when a movie is found twice: largest or smallest (default largest)
Recent How recent is recent (default 8760h = 1 year)
RecentLimit How many recent (default 50)
ReleaseCountries Preferred release countries for ratings and dates
SearchLimit How many items to return (default 100)
SyncInterval How often to automatically resync media from buckets (1h)
PosterSyncInterval How often to cache poster images (24h)
BackdropSyncInterval How often to cache backdrop images (24h)

Recommendations

Movies can be recommended based on date patterns and search queries. It’s a convenient way to watch movies without having to think too hard while you sit on the sofa. Note that the Layout field corresponds to the Go date parsing layouts.

Below is an example set of film recommendations.

Film:
  Recommend:
    When:
      - Name: "Friday the 13th Movies"
        Match: "Fri 13"
        Layout: "Mon 02"
        Query: +character:voorhees

      - Name: "St. Patrick's Day Movies"
        Match: "Mar 17"
        Layout: "Jan 02"
        Query: "+keyword:leprechaun"

      - Name: "Star Wars Day"
        Match: "May 04"
        Layout: "Jan 02"
        Query: +title:"star wars"

      - Name: "Halloween Movies"
        Match: "Oct"
        Layout: "Jan"
        Query: "+keyword:halloween"

      - Name: "Christmas Movies"
        Match: "Dec"
        Layout: "Jan"
        Query: +keyword:christmas

TV Shows 

TV:
  Recent: "8760h"
  RecentLimit: 50
  SearchLimit: 100
  SyncInterval: "1h"
Name Description
CastLimit How many cast members (default 25)
CrewJobs Crew jobs to index (same defaults as Film)
Recent How recent is recent (default 8760h = 1 year)
RecentLimit How many recent (default 50)
ReleaseCountries Preferred release countries for ratings and dates
SearchLimit How many items to return (default 100)
SyncInterval How often to automatically resync media from buckets (1h)
PosterSyncInterval How often to cache poster images (24h)
BackdropSyncInterval How often to cache backdrop images (24h)
StillSyncInterval How often to cache episode still images (24h)

Podcasts 

Podcast:
  RecentLimit: 25
  SearchLimit: 100
  SyncInterval: "1h"
  Series:
    - "https://feeds.twit.tv/twit.xml"
    - "https://www.pbs.org/newshour/feeds/rss/podcasts/show"
    - "http://feeds.feedburner.com/TEDTalks_audio"
Name Description
EpisodeLimit How many episodes to include in a playlist (default 52)
RecentLimit How many recent (default 25)
SearchLimit How many items to return (default 100)
SyncInterval How often to automatically resync from sources (1h)
Series List of Podcasts sources

Users can subscribe to podcasts from the apps and the web UI.

Client

This is the client used with all third-party APIs when syncing media. Using the cache here can make re-syncing significantly faster.

Client:
  MaxAge: "720h"
  CacheDir: "httpcache"
Name Description
MaxAge How long to use cached responses (default 720h = 30 days)
CacheDir Directory to store cached responses (default httpcache)

API Keys

Name Description
FanArt.ProjectKey Takeout uses 93ede276ba6208318031727060b697c8
LastFM.Key Please obtain your own at last.fm
LastFM.Secret Please obtain your own at last.fm
ListenBrainz.Token Used to obtain popular tracks. Obtain your own at listenbrainz.org
TMDB.Key Takeout uses 903a776b0638da68e9ade38ff538e1d3
TMDB.Language Language for TMDB metadata (default en-US)
ImagesSystemd