Server Admin Guide

Server Admin Guide

Important Server Files

Default storage locations:

<world>/music-import/
<world>/music-normalized/
<world>/data/musicxcst/music-index.json

music-index.json stores ownership, file metadata, checksums, status, color, duration, normalized audio paths, preview paths, and creation timestamps. Do not edit it while the server is running.

Client downloads are cached locally in:

<minecraft directory>/musicxcst-cache/

Important Config Keys

maxFileSizeBytes
maxStoragePerPlayerBytes
maxTotalServerStorageBytes
allowedFileExtensions
serverImportFolder
serverNormalizedAudioFolder
normalizedOutputFormat
ffmpegMode
ffmpegPath
ffmpegManagedDownloadAllowed
ffmpegManagedSourceUrl
ffmpegManagedVersion
ffmpegManagedSha256
ffmpegManagedLicense
allowServerSideTranscoding
audioBitrate
sampleRate
previewCacheSeconds
maxMusicDurationEnabled
maxMusicDurationSeconds
maxMusicFilesPerPlayerEnabled
maxMusicFilesPerPlayer
playerLimitMode
clientUploadBytesPerSecond
playbackRadiusBlocks
rangeCheckIntervalTicks
fadeInMilliseconds
fadeOutMilliseconds
clientCacheSizeBytes
absoluteImportSubfolder
allowSingleplayerAbsolutePaths
allowAdminAbsoluteServerPaths
softDeleteEnabled
allowFoundDiscsPlayback
ownerOnlyPlayback
adminBypass
debugLogging

Duration Limits

Duration examples:

150 seconds  = 2:30
600 seconds  = 10:00
3600 seconds = 1:00:00

Set maxMusicDurationEnabled to false for no duration limit. If duration limiting is enabled and FFmpeg cannot determine track duration, the upload is rejected.

Per-Player File Limits

playerLimitMode accepts:

confirm_delete_oldest
auto_delete_oldest
block_new_upload

MusicXCST 0.1.4 counts active tracks for per-player file limits. Deleted, missing, or invalid entries no longer block new uploads.

When deleting an old upload, MusicXCST targets entries owned by that player, updates metadata, removes stored playback files, and removes the reusable uploaded file for the entry.

Public Server Recommendations

• Enable size, duration, and per-player file limits.
• Keep allowAdminAbsoluteServerPaths disabled unless all admins are trusted.
• Use block_new_upload or confirm_delete_oldest for stricter moderation.
• Back up the music index and audio folders before major updates.
• Publish clear rules about uploaded audio rights.
• Keep FFmpeg setup under server owner/admin control.