Media Features

Audio player, video player, transcoding, and media indexing

Overview

copyparty includes a full-featured media player with audio transcoding, tag indexing, playlists, and OS integration. Perfect for self-hosting your music library.

Audio Player

A sophisticated web-based audio player with advanced features.

Key Features

OS Integration

Control playback from your phone’s lockscreen or Windows media controls

Transcoding

Play any audio format via on-the-fly FFmpeg transcoding

Equalizer

Built-in EQ with dynamic range compression

Gapless Playback

Nearly gapless transitions between songs

Supported Formats

Always playable (no FFmpeg needed):

• AAC, FLAC, M4A, MP3, OGG, Opus, WAV

With FFmpeg transcoding:

• AC3, AIF, AIFF, ALAC, ALAW, AMR, APE, AU, DFPWM, DTS
• GSM, IT, M4A, MO3, MOD, MP2, MPC, MPTM, MT2, MULAW
• OKT, RA, S3M, TAK, TTA, ULAW, WMA, WV, XM, XPK
• Videos (audio track extracted)

Player Controls

Click the play link next to an audio file to start playback.

Hotkeys:

• P - Play/Pause
• J/L - Previous/Next song
• U/O - Skip ±10 seconds
• 0-9 - Jump to 0%-90%
• Y - Download current file

Player Configuration

Open the [🎺] media player settings tab:

Switches

• [🔁] Repeat one song forever
• [🔀] Shuffle files in each folder
• [preload] Start loading next track early (reduces silence between songs)
• [full] Full preload (download entire next file - good for unreliable connections)
• [~s] Toggle waveform display in seekbar
• [/np] Enable “now playing” IRC message buttons
• [📻] Enable playlist creation buttons
• [os-ctl] Enable OS lockscreen controls
• [seek] Allow seeking via lockscreen
• [art] Show album art on lockscreen
• [🎯] Auto-scroll to playing song
• [⟎] Shrink playback controls

Folder Playback

• [loop] Loop the current folder
• [next] Continue into next folder

Transcoding Options

Format Selection

Choose which formats to transcode:

• [flac] - Convert FLAC/WAV to Opus/MP3
• [aac] - Convert AAC/M4A to Opus/MP3
• [oth] - Convert all other formats to Opus/MP3

Output Format

Choose transcoding output:

• [opus] - Best quality (Android, PC) - recommended
• [awo] - Opus in WebM container (iOS 17.5+)
• [caf] - Opus in CAF container (iOS 11-17)
• [mp3] - Universal compatibility, lower quality
• [flac] - Lossless (requires --allow-flac)
• [wav] - Uncompressed lossless (requires --allow-wav)

FLAC and WAV transcoding must be explicitly enabled with --allow-flac and --allow-wav due to disk space requirements.

Audio Equalizer

Built-in equalizer and dynamic range compressor.

• Adjustable frequency bands
• Volume boost
• Stereo width control (similar to crossfeed)
• Dynamic range compression
• Reduces pause between songs (helps with gapless playback)

Equalizer not available on iPhone/iPad due to AudioContext breaking background playback on iOS.

Playlists (M3U/M3U8)

Create and play standard M3U playlists.

Creating Playlists

Method 1: Using copyparty

1. Enable [📻] in player settings
2. Click 📻add while songs are playing or selected
3. Click 📻copy to get playlist content
4. Create playlist.m3u and paste content

Method 2: External player

Create playlists in foobar2000, deadbeef, or any media player. Edit paths to match server URLs.

Playing Playlists

Click an .m3u or .m3u8 file and choose Play.

Playlists can include songs across folders but don’t support filekeys/dirkeys. Users need read/get access to all files.

Video Player

Basic video playback with gallery integration.

Features

• Click video files to play inline or fullscreen
• Navigate through videos in folder with J/L or arrow keys
• Play video files as audio (audio track only, no video bandwidth)
• Loop ranges with [ and ] hotkeys

Hotkeys

• J/L, ←/→ - Previous/Next video
• F - Fullscreen
• P/K/Space - Play/Pause
• U/O - Skip ±10 seconds
• 0-9 - Jump to 0%-90%
• M - Mute
• C - Continue to next video
• V - Loop current video
• [ - Set loop start
• ] - Set loop end

Audio from Video

Add ?v to any video/audio/image link to open it in the media player (audio-only for videos).

Media Indexing

Index audio tags for searching and organization.

Enable Tag Indexing

# Index tags on upload and scan existing files
copyparty -e2dsa -e2ts

[global]
  e2dsa  # scan all files on startup
  e2ts   # index audio/video tags

Configuring Tags

Display tags (indexed and shown):

copyparty -mte artist,title,album

Hidden tags (indexed but hidden by default):

copyparty -mth .dur,.bpm,genre

Tag mappings (combine multiple tags):

# Display 'qux' tag from 'foo' or 'bar' (prefer foo)
copyparty -mtm qux=foo,bar -mte artist,title,qux

Config File Example

[global]
  e2dsa
  e2ts
  mte: artist,title,album,.tn  # track number is numeric (.tn)
  mth: .dur,.bpm,genre,fmt     # hidden by default
  mtm: key=initialkey,key      # map 'key' tag

[/music]
  /mnt/music
  accs:
    r: *
  flags:
    mte: +.up_at  # also show upload time

Tag Sources

Mutagen (default):

• Fast (~20x faster than FFprobe)
• Supports MP3, FLAC, Opus, M4A, WAV, AIF

FFprobe (with --no-mutagen):

• Slower but more comprehensive
• Additional tags: melodic key, video resolution, framerate
• Processes all FFmpeg-supported formats

Available Metadata Tags

Common tags include:

• artist, title, album
• .tn (track number), .dur (duration - numeric tags start with .)
• genre, date, composer
• .bpm, key, comment
• .resw, .resh (video resolution)
• fmt (format/codec)

Custom Tag Parsers

Extend metadata with external programs.

[/music]  
  /mnt/music
  flags:
    mtp: .bpm=~/bin/audio-bpm.py           # basic BPM detection
    mtp: key=f,t5,~/bin/audio-key.py       # force, 5sec timeout
    mtp: ext=an,~/bin/file-ext.py          # non-audio files only

Parser flags:

• f - Force/overwrite existing tags
• t5 - 5 second timeout
• ay - Audio files only (default)
• an - Non-audio files only
• ad - All files

See parser examples.

Transcoding Configuration

Server-Side

# Allow FLAC transcoding output
copyparty --allow-flac

# Allow WAV transcoding output  
copyparty --allow-wav

# Set tag scan timeout (default 60 seconds)
copyparty --mtag-to 10

Per-Volume

[/hifi]
  /mnt/hifi
  flags:
    aconvt: 30   # transcoding timeout in seconds

Advanced Features

Folder Thumbnails from Audio

With -e2dsa enabled, copyparty extracts album art for folder thumbnails.

Cover image priority:

1. folder.png / folder.jpg
2. cover.png / cover.jpg
3. .folder.png / .folder.jpg (dotfiles)
4. First image in folder
5. Embedded album art

Customize with:

copyparty --th-covers folder.png,cover.jpg,front.png

Sort by Metadata

# Sort by album, track number, artist, title
copyparty --sort tags/Circle,tags/.tn,tags/Artist,tags/Title

[/music]
  /mnt/music
  flags:
    sort: tags/Artist,tags/Album,tags/.tn

Extended File Attributes (Linux)

Index xattrs as metadata:

# Index specific xattrs
copyparty --db-xattr user.rating,user.genre -mte +user.rating,user.genre

# Index all xattrs
copyparty --db-xattr ~~ -mte +*

Set xattrs:

setfattr -n user.rating -v "5/5" song.mp3

Performance Tuning

• Use Mutagen (default) for faster tag scanning
• Lower --mtag-to timeout if your filesystem is reliable (default 60s is for ZFS/network)
• Enable waveform caching with reasonable --th-maxage
• Disable video transcoding with --no-vthumb if not needed

Example: Music Server

[global]
  e2dsa              # full filesystem indexing
  e2ts               # audio tag indexing  
  no-robots          # prevent search engine indexing
  theme: 2           # flat pm-monokai theme
  mte: artist,title,album,.tn,.dur
  mth: .bpm,key,genre,fmt
  sort: tags/Artist,tags/Album,tags/.tn

[/music]
  /mnt/nas/music
  accs:
    r: *             # public read-only
  flags:
    mtp: .bpm=f,audio-bpm.py
    mtp: key=f,audio-key.py

copyparty -c music-server.conf