Media Server Setup

Configure copyparty as a media server with audio/video playback and metadata indexing

Overview

copyparty includes a powerful media player that supports almost every audio and video format, with features like playlist management, audio transcoding, and metadata-based searching.

Prerequisites

For the best media server experience, install these optional dependencies:

Debian/Ubuntu

apt install --no-install-recommends python3-pil ffmpeg

Basic Media Server Setup

Configuration File Setup

For a production media server, use a configuration file:

media-server.conf

[global]
  e2dsa      # index all files on startup
  e2ts       # scan audio/video tags
  theme: 2   # flat dark theme (looks nice for media)
  
[accounts]
  alice: secretpass
  bob: otherpass

[/music]
  /mnt/nas/music
  accs:
    r: alice, bob  # both users can access
  flags:
    mte: artist,album,title,.tn,date,genre  # tags to display

[/videos]
  /mnt/nas/videos  
  accs:
    r: alice, bob
  flags:
    e2d, e2t           # enable indexing
    dvthumb            # disable video thumbnails (saves CPU)

Start the server:

python copyparty-sfx.py -c media-server.conf

Advanced Media Features

Audio Transcoding

The media player can transcode unsupported formats on-the-fly. Enable opus transcoding for mobile devices:

python copyparty-sfx.py -e2dsa -e2ts -v /mnt/music:/music:r

In the web UI, click [🎺] (media player settings):

• Enable [oth] to transcode uncommon formats
• Enable [flac] to transcode FLAC files for bandwidth savings
• Choose [opus] or [mp3] as the output format

Custom Sort Order

Sort files by album, track number, artist, and title:

python copyparty-sfx.py -e2dsa -e2ts \
  --sort tags/album,tags/.tn,tags/artist,tags/title \
  -v /mnt/music:/music:r

Or in config file:

[/music]
  /mnt/music
  accs:
    r: *
  flags:
    e2dsa, e2ts
    sort: tags/album,tags/.tn,tags/artist,tags/title

RSS Feeds for Podcasts

Enable RSS feeds for podcast clients:

python copyparty-sfx.py -e2dsa -e2ts \
  -v /mnt/podcasts:/podcasts:r:c,rss

Access the RSS feed:

http://your-server:3923/podcasts/?rss&fext=mp3

Add parameters:

• ?rss&recursive - Include subfolders
• ?rss&fext=mp3,opus - Only include specific formats
• ?rss&nf=50 - Limit to 50 newest files
• ?rss&pw=password - Include password in feed

Video Thumbnails

Video thumbnails are generated automatically with FFmpeg:

python copyparty-sfx.py -e2dsa -v /mnt/videos:/videos:r

Disable video thumbnails to save CPU:

[/videos]
  /mnt/videos
  flags:
    dvthumb  # disable video thumbnails

Playlist Support

Create and use M3U playlists:

1. Enable playlist creation

   In the web UI, open [🎺] media player settings and enable [📻] create-playlist.

2. Add songs to playlist

   • Click [📻add] while a song is playing
   • Or select multiple files and click [📻add]
3. Save the playlist

   • Click [📻copy] to copy to clipboard
   • Create a new file with .m3u extension
   • Paste the playlist content
4. Play the playlist

   Click on any .m3u file and choose “Play”

Metadata Indexing

Supported Audio Formats

copyparty can extract metadata from:

• MP3, FLAC, Opus, Ogg Vorbis
• M4A, AAC, ALAC
• WMA, WAV, AIFF
• Module formats (MOD, XM, S3M, IT)
• And many more with FFmpeg

Additional Metadata with Plugins

Use external scripts to add BPM and key detection:

[/music]
  /mnt/music
  flags:
    e2dsa, e2ts
    mte: artist,title,.bpm,key  # display BPM and key
    mtp: .bpm=~/bin/audio-bpm.py     # detect BPM
    mtp: key=~/bin/audio-key.py      # detect key

See example plugins in the repo.

Hide Tags by Default

Index tags for searching but don’t display them:

python copyparty-sfx.py -e2ts \
  -mte artist,album,title \
  -mth genre,date,.bpm \
  -v /mnt/music:/music:r

• -mth - Tags to hide (still searchable)
• Users can unhide them in the [⚙️] settings tab

Search Features

With indexing enabled, users can search by:

Tag-based search

Open [🔎] search tab:

• Name: demetori - Find files with “demetori” in filename
• Tags: artist:*nhato* - Find by artist tag
• Raw query: tags.artist like '%touhou%' - SQL-style queries

File content search

Drag and drop files into the upload area and select “Search” to find duplicates by content hash.

Performance Optimization

Exclude large files from indexing

Skip hashing for large video files:

[/videos]
  /mnt/videos
  flags:
    e2dsa
    nohash: \.(mkv|mp4|avi)$  # don't hash video files

Move database to SSD

Store the index database on a faster disk:

[global]
  hist: /mnt/ssd/copyparty-cache

[/music]
  /mnt/nas/music
  flags:
    e2dsa, e2ts

Disable thumbnails for large libraries

python copyparty-sfx.py -e2dsa -e2ts --no-vthumb \
  -v /mnt/music:/music:r

Disables video thumbnails but keeps audio spectrograms.

Set thumbnail cache size

python copyparty-sfx.py --th-maxage 2592000 \
  -v /mnt/music:/music:r

Thumbnails expire after 30 days (2592000 seconds).

Mobile Access

iOS Shortcuts

Create shortcuts to quickly access your music:

1. Open Shortcuts app
2. Create new shortcut
3. Add “Open URL” action
4. Set URL: http://your-server:3923/music

Android App

Use the copyparty Android app for quick uploads and access.

Progressive Web App

Add copyparty to your home screen:

1. Open in mobile browser
2. Tap “Add to Home Screen”
3. Access like a native app

Example: Complete Music Server

complete-media.conf

[global]
  e2dsa               # scan all files on startup
  e2ts                # index audio/video tags
  theme: 2            # dark theme
  grid                # grid view by default
  no-robots           # hide from search engines
  force-js            # disable plain HTML (cleaner)

[accounts]
  alice: pass1
  bob: pass2
  
[/music]
  /mnt/nas/music
  accs:
    r: alice, bob
  flags:
    rss                           # enable RSS feeds
    mte: artist,album,title,.tn,date,genre
    sort: tags/album,tags/.tn,tags/artist,tags/title
    th-covers: folder.jpg,cover.jpg,folder.png

[/audiobooks]
  /mnt/nas/audiobooks
  accs:
    r: alice, bob
  flags:
    e2dsa, e2ts
    opds              # enable OPDS for e-readers
    rss

Troubleshooting

Tags not appearing

• Ensure -e2ts is set
• Tags must be in -mte to display
• Run with -e2tsr once to rebuild tag database
• Check that FFmpeg or Mutagen is installed

Thumbnails not working

• Install FFmpeg and/or Pillow
• Check file permissions on .hist/ folder
• Some formats need specific FFmpeg builds
• Use --th-ff-jpg for compatibility

Slow indexing

• Use --no-hash for large video files
• Move database to SSD with --hist
• Reduce --mtag-mt (default is CPU count)

Music stops on mobile

Android: disable battery optimization for your browser app.

iOS: known browser limitations, try enabling preload in player settings.

Next Steps

• Configure write-only folders for user uploads
• Enable deduplication to save space
• Set up authentication with SSO
• Learn about file sharing permissions