Configuration

Configuration Guide

The configuration file is named config.json and is located in the same directory as the executable. If it does not exist, a default configuration will be generated automatically upon startup.

Tip: Most common settings (like adding/removing shared folders) can be done directly in the "Settings" on the web interface without manually editing the file.

Runtime Files

• config.json: Runtime configuration (contains local paths; do not commit).
• msp.db: SQLite database (stores media index and playback progress; do not commit).
• msp.db-shm, msp.db-wal: SQLite temporary files (do not commit).

Full Configuration Example

{
  "port": 8099,
  "maxItems": 0,
  "shares": [
    {
      "label": "Movies",
      "path": "D:\\Movies"
    },
    {
      "label": "Music",
      "path": "E:\\Music"
    }
  ],
  "logLevel": "info",
  "logFile": "msp.log",
  "blacklist": {
    "extensions": [".tmp", ".bak", "^\\.~.*$"],
    "filenames": ["desktop.ini", "thumbs.db"],
    "folders": ["$RECYCLE.BIN", "System Volume Information"],
    "sizeRule": "<1KB"
  },
  "features": {
    "speed": true,
    "speedOptions": [0.5, 0.75, 1, 1.25, 1.5, 2],
    "quality": false,
    "captions": true,
    "playlist": true
  },
  "ui": {
    "defaultTab": "video",
    "showOthers": false
  },
  "playback": {
    "audio": {
      "enabled": true,
      "shuffle": false,
      "remember": true,
      "scope": "all",
      "transcode": false
    },
    "video": {
      "enabled": true,
      "scope": "folder",
      "transcode": false,
      "resume": true,
      "encoding": {
        "hwAccel": "auto",
        "maxJobs": 0
      }
    },
    "image": {
      "enabled": true,
      "scope": "folder"
    }
  },
  "security": {
    "ipWhitelist": [],
    "ipBlacklist": [],
    "pinEnabled": false,
    "pin": "0000"
  }
}

Field Details

1. Basic Settings (port, shares, log, maxItems)

• port: Server listening port, default is 8099.
• maxItems: Maximum number of items to scan.
  • 0: Recommended. Unlimited full scan, utilizing SQLite for incremental updates. Initial scan takes time, but subsequent startups are near-instant.
  • >0 (e.g., 8000): Limit the number of scanned items. Useful for quick previews or testing. Note: Scanning stops completely after reaching this limit.
• shares: List of shared directories.
  • label: Name alias displayed on the web interface.
  • path: Local absolute path (Note: use double backslashes \\ on Windows).
• logLevel: Log verbosity level.
  • Values: debug, info (default), error, silent.
• logFile: Path to the log file.
  • Default: msp.log.
  • Stores detailed logs (including debug info) to keep the console clean.

2. Blacklist Filtering (blacklist)

Supports powerful file filtering. Matched files will not be shown in the list.

• extensions: List of blocked file extensions.
  • Supports normal extensions (e.g., .tmp).
  • Supports Regex (e.g., ^\\.~.*$ blocks temporary files starting with ~).
• filenames: List of blocked filenames.
  • Supports exact match (e.g., desktop.ini).
  • Supports Regex.
• folders: List of blocked folder names.
  • Matches any directory name in the path.
• sizeRule: File size filtering rules.
  • Greater/Less than: >100MB, <10KB.
  • Range: 10MB-1GB (blocks files between 10MB and 1GB).
  • Units: B, KB, MB, GB, TB (case-insensitive).

3. Feature Toggles (features)

• speed: Enable playback speed control.
• speedOptions: Custom speed options list.
• captions: Enable subtitle support (auto-loads .vtt / .srt with same name).
• playlist: Enable playlist sidebar.

4. UI Settings (ui)

• defaultTab: Default opening tab (video / audio / image / other).
• showOthers: Whether to show non-media files in the "Other" tab.

5. Playback Behavior (playback)

Controls default behavior for media types.

• audio:
  • shuffle: Default shuffle mode.
  • remember: Remember playback progress.
  • scope: Playlist scope (all for all files, folder for current folder).
  • transcode: Enable FFmpeg transcoding for unsupported formats (default: false).
• video:
  • enabled: Enable video playback.
  • scope: Playlist scope (folder / all).
  • transcode: Enable FFmpeg transcoding for unsupported formats (default: false).
  • resume: Remember playback progress (default: true).
  • encoding: Hardware acceleration settings (v0.9.0+).
    • hwAccel: Hardware encoder mode ("auto" (default), "none", "nvenc", "qsv", "amf", "vaapi", "videotoolbox").
    • maxJobs: Max concurrent transcode sessions (0 = auto: 2 for software, 4 for hardware).
• image:
  • enabled: Enable image viewer.
  • scope: Browsing scope (folder / all).

6. Security Settings (security) (v0.7.0+)

Controls access permissions and authentication.

• ipWhitelist: IP Whitelist (Array)

  • No restriction if empty.
  • If not empty, only IPs in this list can access.
  • Supports single IP: "192.168.1.100"
  • Supports CIDR range: "192.168.1.0/24", "10.0.0.0/8"

• ipBlacklist: IP Blacklist (Array)

  • IPs in this list will be denied access.
  • Supports single IP and CIDR range.
  • Higher priority than whitelist.

• pinEnabled: Enable PIN authentication (Boolean)

  • true: Enabled, requires PIN to access.
  • false: Disabled (default).

• pin: PIN Code (String)

  • Default: "0000".
  • Can be any string.
  • 4-6 digits recommended.

Config Hot-Reload (v0.7.0+)

Starting from v0.7.0, MSP supports configuration hot-reload:

• Modify config.json without restarting the server.
• Changes take effect within 2 seconds.
• Server log shows: Config file changed, reloading... and Config reloaded successfully.
• Applies to all settings (Security, Shares, etc.).

Playback Notes (v0.8.11+)

• Enabling transcoding does not mean all media will be transcoded.
• Common MP4 (H.264/AAC) remains on direct play by default.
• Preemptive transcoding is mainly for high-risk containers (AVI/WMV); other formats fallback to transcode only on real playback failure.