Configure FFmpeg paths, subtitle extraction, and media processing options for video thumbnails and subtitle support.

Basic Configuration

Path to the directory where ffmpeg and ffprobe executables are installed (only needed if not in PATH):

YAML 
1
2
3

integrations:
  media:
    ffmpegPath: "/usr/local/bin"  # Directory containing ffmpeg and ffprobe

Subtitle Extraction

For large videos, you may notice a 20-30 second delay loading a video for the first time if you enable this. Subsequent views within a 24 hour period will load cached subtitles for faster load times.

This feature is very useful – but can be demanding if many different videos are previewed at once. So, this is also disabled by default for shares and must be configured at the share level if you want share link users to view embedded subtitles as well.

Subtitle extraction requires configuration at two levels:

Server-Level Configuration

YAML 
1
2
3

integrations:
  media:
    extractEmbeddedSubtitles: false  # Enable server-wide subtitle extraction

Must be enabled at the server level first to allow subtitle extraction functionality.

Share-Level Configuration

For shares, subtitle extraction must be enabled in both places:

Installation by Platform

FFmpeg is included in the official FileBrowser image, no installation or configuration needed.

Installation:

BASH 
1

sudo apt update && sudo apt install ffmpeg

Configuration:

YAML 
1
2
3

integrations:
  media:
    ffmpegPath: "/usr/bin"

Installation (using Homebrew):

BASH 
1

brew install ffmpeg

Configuration:

YAML 
1
2
3

integrations:
  media:
    ffmpegPath: "/usr/local/bin"

Installation:

  1. Download FFmpeg from ffmpeg.org
  2. Extract to a directory (e.g., C:\Program Files\ffmpeg)
  3. Add the bin directory to your system PATH

Configuration:

YAML 
1
2
3

integrations:
  media:
    ffmpegPath: "C:\\Program Files\\ffmpeg\\bin"

Advanced Configuration

Format Support

Control which media formats support thumbnail previews:

YAML 
1
2
3
4
5
6
7

integrations:
  media:
    convert:
      imagePreview:
        heic: false  # Enable HEIC image preview conversion (default false)
      videoPreview:
        mp4: false    # Disables MP4 video thumbnails (default: true)

Supported video formats: 3g2, 3gp, asf, avi, f4v, flv, m2ts, m4v, mkv, mov, mp4, mpeg, mpg, ogv, ts, vob, webm, wmv

Debug Mode

Enable debug output for troubleshooting:

YAML 
1
2
3

integrations:
  media:
    debug: false  # Enable FFmpeg debug output

Performance Settings

Cache Directory

A high perfomrance directory for caching is needed – see CacheDir config for more details.

Processing Workers

YAML 
1
2

server:
  numImageProcessors: 4  # Number of parallel thumbnail processors

Defaults to the number of CPU cores available. FFmpeg operations use half this number (minimum 1 worker).

Environment Variables

Configure via environment variables instead of config file:

BASH 
1
2

# FFmpeg path
export FILEBROWSER_FFMPEG_PATH="/usr/local/bin"

Complete Configuration Example

Full media integration configuration:

YAML 
 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17

server:
  numImageProcessors: 4

integrations:
  media:
    ffmpegPath: "/usr/bin"
    debug: false
    extractEmbeddedSubtitles: true  # Enable subtitle extraction
    convert:
      imagePreview:
        heic: true  # Enable HEIC conversion
      videoPreview:
        mp4: true
        mkv: true
        avi: true
        mov: true
        webm: true

Test in FileBrowser

  1. Navigate to a video file in FileBrowser
  2. Ensure user profile settings have “video previews” enabled
  3. Check if a thumbnail preview is generated
  4. For subtitle extraction, enable it in share settings and verify subtitles appear in the video player

Next Steps