Skip to main content

​
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: 
apt install --no-install-recommends python3-pil ffmpeg

​
Basic Media Server Setup

1
Share your music library
2
Start with a simple read-only music server:
3
python copyparty-sfx.py -e2dsa -e2ts -v /mnt/music:/music:r
4
  • -e2dsa - Scan and index all files on startup
  • -e2ts - Index audio/video metadata tags
  • /mnt/music:/music:r - Share music folder as read-only
    • 5
    Enable thumbnails and spectrograms
    6
    Thumbnails are enabled by default when FFmpeg/Pillow is installed:
    7
    python copyparty-sfx.py -e2dsa -e2ts -v /mnt/music:/music:r
    8
    Audio files get spectrogram thumbnails automatically. Disable with --no-athumb if needed.
    9
    Configure metadata display
    10
    Customize which tags appear in the file listing:
    11
    python copyparty-sfx.py -e2dsa -e2ts \
  -mte artist,album,title,.tn,date \
  -v /mnt/music:/music:r
    12
  • -mte - Metadata Tags to Extract/display
  • .tn - Track number (dot prefix = numeric value)
  • Common tags: artist, album, title, date, .bpm, genre
    • 13
    Add password protection
    14
    Create a private media server:
    15
    python copyparty-sfx.py -e2dsa -e2ts \
  -a alice:secretpass \
  -v /mnt/music:/music:r,alice

    ​
    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: 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

    Skip hashing for large video files:
    [/videos]
  /mnt/videos
  flags:
    e2dsa
    nohash: \.(mkv|mp4|avi)$  # don't hash video files
    Store the index database on a faster disk:
    [global]
  hist: /mnt/ssd/copyparty-cache

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

    python copyparty-sfx.py -e2dsa -e2ts --no-vthumb \
  -v /mnt/music:/music:r
    Disables video thumbnails but keeps audio spectrograms.
    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

    • 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
    • Install FFmpeg and/or Pillow
    • Check file permissions on .hist/ folder
    • Some formats need specific FFmpeg builds
    • Use --th-ff-jpg for compatibility
    • Use --no-hash for large video files
    • Move database to SSD with --hist
    • Reduce --mtag-mt (default is CPU count)
    Android: disable battery optimization for your browser app.iOS: known browser limitations, try enabling preload in player settings.

    ​
    Next Steps

    Build docs developers (and LLMs) love

    Get started for freeTalk to us