streama Documentation

Technical Documentation: streamaserver/streama

ℹ️ Provenance: Multi-Tier Ingestion · CodeWiki Reference

Overview (`README.md`) Copy Section

STREAMA

Docs: https://docs.streama-project.com/

Ever had a huge bookshelf full of shows and movies? Ever wanted to digitalize them, but didn't have a good way of organizing the files? Worry no more! Streama is your own personal Netflix for just such a purpose!

Live-Demo Copy Chapter

https://streama.demo-version.net/
credentials: username: demoUser | password: demoUser
Feel free to play around there as much as you like (everything is reset at night)
We will keep this demo updated with our newest releases as they come, so that you can check out new features there first before deciding to deploy them in your own environments.

Donate Copy Chapter

If you want to donate to the developer via bitcoin use 17rCUEX6KYQ8ZM4w39ttEUL7SUDnGCpcWq

Table of contents: Copy Chapter

• Getting Started
• Downloads
• The Application
  • Settings
  • The Dashboard
  • The Player
  • The Admin-Panel
  • Accessing existing files
  • The Users
• Technical Details
• Changelog
• Roadmap
• Known Issues
• Contributing
• License

Getting Started

• Installation and first-time setup

If you have any issues getting started, feel free to chat with us on Discord. We are more than happy to assist and then improve the docs accordingly.

Downloads

• Stable and beta versions see the GitHub releases

The Application

Settings Copy Section

When you first run the application, you will be redirected to the settings page. Here you enter your desired upload directory for the video files, your theMovieDb.org API key and a different base URL if so desired (useful for remote hosting).

Once you made adjustments to any of the settings, make sure to validate the value before saving.

• For the API-Key, the validation checks against theMovieDb.org to see if you've entered a valid API-key.
• For the upload directory, the application checks if it has read/write permissions for it.

The Dashboard Copy Section

On the dashboard, a user can see their recently watched TV-shows and Movies and their progress (they can continue where they left off) as well start new shows and movies that they haven't yet seen. The "Continue Watching" Feature works by periodically updating the database (only while watching, of course!) with info about the currently watched Video and how far it has been seen.

If a Movie or Episode does not contain any video-files, it won't show up in the dashboard.

The Player Copy Section

The Streama-Player is (heavily) inspired by Netflix, so you get all the good stuff from there. For Shows, there is a "next episode" button and a handy episode/season browser. There are also the basics: volume-control, play/pause, and fullscreen.
Later down the road I will add a feature to add subtitles and switch between video-files (for instance for different quality uploads).
The player is HTML5-based and has only really been tested in Chrome so far.

The Episode Browser

I am especially proud of the Episode-Browser, which aims to function just like on Netflix. By default, the current video files season is selected. The user gets an overview of which other episodes there are in the season, how many seasons there are, and, as an added feature, the user sees all the added episodes, even if no video-files are added to them (thus greyed out).

The Admin-Panel Copy Section

One of the most important things to me was to make managing shows, movies, and episodes as easy and fun as possible. For this, I made heavy use of the API from theMovieDatabase.org, which auto-fills the episodes, shows and movies with useful information and great images. This eases the user's role in adding content.

For example, creating a new TV-show and the episodes for the first season looks something like this:

Uploading video-files for each episode is as easy as drag-and-drop!

Accessing existing files Copy Section

If you want to avoid uploading every file, use our new and improved "Local File" Feature instead. You can define a local directory (I use one directly in which I created symlinks to all my mounted drives) and then you can either use the local file browser for individual movies / tv-Shows or you can use the bulk-create feature.

The local file browser

You can access the local file browser from any movie or TV-show (anywhere where you would otherwise upload a file). Note: You need to first define the local directory in the settings.

Bulk-Create from File

This MR addresses the issue "Batch Add Files #241".
Note: the TV-Show does not have to be present in order for this to work. Everything will be created by the backend.

Running matcher & previewing the result

adding single matched file

adding files in bulk

Customizing the Matcher

Just like in Emby or Kodi, the matcher-regex can be altered. The two defaults are
Movie: /^(?<Name>.*)[_.]\(\d{4}\).*/
TvShow/Episode: /^(?<Name>.+)[._]S(?<Season>\d{2})E(?<Episode>\d{2,3}).*/

In order to customize the regex, just add the regex in the bottom of the application.yml like so:

streama:
  regex:
    movies: ^(?<Name>.*)[_.]\(\d{4}\).*
    shows: ^(?<Name>.+)[._]S(?<Season>\d{2})E(?<Episode>\d{2,3}).*

The Users Copy Section

Users can be invited and managed in the admin panel. By default, they are non-admins, meaning they can only view videos, not create them. You can make them admins with the press of a button. Since there is user-administration in place, I plan on expanding on this a lot! Another feature I want to add is the ability for users to add and administer some form of playlists. There is a lot of potentials to make this even better!

Technical Details

This application is web-based, the server-side is written on Grails 3 with SpringSecurity for login & user-handling. For all the front-end components, AngularJS is used and the player is completely HTML5-based. The application is essentially split into Grails for a REST-API, and AngularJS for the frontend.

Streama uses the awesome API from theMovieDatabase for all media-metadata.

Changelog

Please refer to the description of each release or the git log.

Roadmap

Streama is still very much a work-in-progress. We will be adding new features and bug-fixes often, but this is a hobby project for the core-contributors, so the time that we can spend on it is limited.

For all our feature and bug tracking, we use the Issues Section. Streama's 'roadmap' is currently to work through the feature requests and improvements that are in the issue tracker. Take a look at the milestones for what we intend to add for upcoming releases.

Contributing

Features, Improvements, and Bugfixes Copy Section

Streama currently only has ~2-3 core-contributors so we are grateful for any extra contributions. Send through a Pull Request and we will review it ASAP.

If you're not sure what to work on, take a look at the issues. There are lots to do!

Translations Copy Section

If you want to contribute a translation, please follow the guide here.

Known Issues

• There is no video-conversion currently, meaning you are reliant upon HTML5 browser compatibilities. Server-side conversion is on our roadmap. See Issue #440

License

Streama is distributed under the terms of the MIT license.
See LICENSE.md for details.

Convert Audio (`docs/convert-audio.md`) Copy Section

Converting Audio for Streama Compatibility

This guide explains how to convert audio tracks in video files for better streaming compatibility.

Why Convert Audio? Copy Chapter

Many video files use EAC3 (Dolby Digital Plus) or DTS audio codecs that have poor browser/streaming support. Converting to AAC ensures compatibility with web players like Streama.

Prerequisites Copy Chapter

• ffmpeg installed (brew install ffmpeg on macOS)

Step 1: Check Current Audio Format Copy Chapter

ffprobe -v error -show_entries stream=index,codec_name,codec_type,channels:stream_tags=language -of json "video.mkv"

Look for the audio stream:

{
  "index": 1,
  "codec_name": "eac3",
  "codec_type": "audio",
  "channels": 6,
  "tags": {
    "language": "eng"
  }
}

Step 2: Convert Audio to AAC Copy Chapter

Basic Conversion (Preserves All Streams) Copy Section

ffmpeg -i "input.mkv" \
  -map 0 \
  -c:v copy \
  -c:a aac -b:a 384k -ac 6 \
  -c:s copy \
  "output.mkv"

Explanation:

• -map 0 copies all streams from input
• -c:v copy keeps video as-is (no re-encoding)
• -c:a aac -b:a 384k converts audio to AAC at 384 kbps
• -ac 6 preserves 5.1 surround (6 channels)
• -c:s copy keeps subtitles as-is

Stereo Downmix (Smaller File) Copy Section

ffmpeg -i "input.mkv" \
  -map 0 \
  -c:v copy \
  -c:a aac -b:a 192k -ac 2 \
  -c:s copy \
  "output.mkv"

Audio Codec Compatibility Copy Chapter

Recommended Bitrates Copy Chapter

In-Place Replacement Copy Chapter

To replace the original file:

ffmpeg -i "video.mkv" -map 0 -c:v copy -c:a aac -b:a 384k -ac 6 -c:s copy "video.fixed.mkv"
mv -f "video.fixed.mkv" "video.mkv"

Batch Processing Copy Chapter

Convert all MKV files in a directory:

for f in *.mkv; do
  ffmpeg -i "$f" -map 0 -c:v copy -c:a aac -b:a 384k -c:s copy "${f%.mkv}.fixed.mkv" -y
  mv -f "${f%.mkv}.fixed.mkv" "$f"
done

Troubleshooting Copy Chapter

Audio out of sync Copy Section

Add -async 1 to the ffmpeg command.

"Discarding too many packets" Copy Section

Try adding -max_muxing_queue_size 1024.

File size increased significantly Copy Section

Video was re-encoded. Ensure -c:v copy is present.

Extract Subtitles (`docs/extract-subtitles.md`) Copy Section

Extracting Subtitles from Video Files

This guide explains how to extract subtitle tracks from MKV video files using ffmpeg.

Prerequisites Copy Chapter

• ffmpeg installed (brew install ffmpeg on macOS)

Step 1: Analyze the Video File Copy Chapter

First, check what subtitle tracks are available:

ffprobe -v error -show_entries stream=index,codec_name,codec_type:stream_tags=language,title -of json "video.mkv"

This outputs JSON showing all streams. Look for entries with "codec_type": "subtitle".

Example output:

{
  "index": 3,
  "codec_name": "subrip",
  "codec_type": "subtitle",
  "tags": {
    "language": "eng",
    "title": "English"
  }
}

Step 2: Extract Subtitles Copy Chapter

Extract a Single Subtitle Track Copy Section

Use the stream index from Step 1:

ffmpeg -i "video.mkv" -map 0:3 -c:s srt "output.srt" -y

• -map 0:3 selects stream index 3 from input 0
• -c:s srt converts to SRT format
• -y overwrites output without prompting

Extract Multiple Subtitle Tracks Copy Section

Extract multiple tracks in one command:

ffmpeg -i "video.mkv" \
  -map 0:3 -c:s srt "video.English.srt" \
  -map 0:35 -c:s srt "video.Swedish.srt" \
  -y

Common Subtitle Formats Copy Chapter

Tips Copy Chapter

• Finding language codes: Common codes are eng (English), swe (Swedish), ger (German), fre (French)
• Forced subtitles: These only show when foreign languages are spoken (marked as "forced" in title)
• SDH subtitles: Include descriptions for deaf/hard of hearing viewers

Troubleshooting Copy Chapter

"Stream not found" Copy Section

The stream index may have changed. Re-run ffprobe to verify.

Image-based subtitles Copy Section

PGS/VOB subtitles are images, not text. You'll need OCR tools like SubtitleEdit to convert them.

Sample Application.Yml (`docs/sample_application.yml`) Copy Section

Place this file next to the streama-[version].war and rename to application.yml with your own settings

environments:
production:
dataSource:

driverClassName: 'com.mysql.jdbc.Driver'

url: jdbc:mysql://localhost/streama

username: root

password:

driverClassName:  'org.h2.Driver'
        url: jdbc:h2:./streama;MVCC=TRUE;LOCK_TIMEOUT=10000;DB_CLOSE_ON_EXIT=FALSE
        username: root
        password:
    server:
        port: 8080

streama:
regex:
movies: ^(?.)[._ ](\d{4}).
shows:
- ^(?.+)[._ ]SsEe.* # example: "House.MD.S03E04.h264.mp4"
- ^(?.+)._ x(?\d{2,3}).* # example: "House.MD.03x04.h264.mp4"
- ^(?\d{2})-(?\d{2,3})-(?.?)-. # example: "02-05-Dr. House-Tanz_ums_Feuer-cineonws.mp4"
- ^(?.?)(?\d{1,3})x(?\d{2}). # example: "Castle4x06DaemonsWebdl480pOktober242011rC.mkv(jkuzt).mp4"

Plans 2026 01 03 Audio Transcoding Design (`docs/plans/2026-01-03-audio-transcoding-design.md`) Copy Section

On-the-fly Audio Transcoding Feature Design

Overview Copy Chapter

Add on-the-fly audio transcoding to Streama to convert incompatible audio codecs (EAC3, AC3) to browser-compatible AAC format. FFmpeg is optional and the feature is disabled if not installed.

Architecture Copy Chapter

┌─────────────────────────────────────────────────────────────────┐
│                        STREAMA SERVER                           │
├─────────────────────────────────────────────────────────────────┤
│  Settings                                                       │
│  ├── ffmpegPath: auto-detected or manual                       │
│  ├── ffprobePath: auto-detected or manual                      │
│  ├── transcodingEnabled: boolean (default false)               │
│  └── transcodeCacheDir: path for cached audio files            │
├─────────────────────────────────────────────────────────────────┤
│  File Domain (extended)                                         │
│  ├── audioCodec: String (eac3, aac, ac3, etc.)                 │
│  ├── needsTranscoding: Boolean                                  │
│  └── transcodedAudioPath: String (path to cached .aac)         │
├─────────────────────────────────────────────────────────────────┤
│  New Services                                                   │
│  ├── FfmpegService        - detect, probe, transcode            │
│  └── TranscodingService   - orchestrate, queue, cache mgmt      │
├─────────────────────────────────────────────────────────────────┤
│  Cache Directory                                                │
│  └── {uploadDir}/transcode-cache/                               │
│      └── {sha256}.aac     - transcoded audio streams            │
└─────────────────────────────────────────────────────────────────┘

User Flows Copy Chapter

Flow 1: Admin enables transcoding Copy Section

1. Admin goes to Settings
2. System auto-detects FFmpeg in PATH
3. If found, shows "FFmpeg detected at /usr/bin/ffmpeg"
4. If not found, shows manual path input with install instructions
5. Admin enables "Audio Transcoding"
6. System validates FFmpeg works

Flow 2: File added to video Copy Section

1. User adds file to Movie/Episode (upload, local file, or existing)
2. If transcoding enabled, system probes file with ffprobe
3. Stores audioCodec in File domain
4. Sets needsTranscoding = true if codec is incompatible (eac3, ac3, dts)

Flow 3: User plays video needing transcoding Copy Section

1. User clicks play on video
2. Frontend requests video
3. If file.needsTranscoding && !file.transcodedAudioPath:
   • Return 202 Accepted with transcoding status
   • Frontend shows "Preparing audio..." spinner
   • Server transcodes audio only to AAC (ffmpeg -vn -c:a aac)
   • Stores result in cache directory
   • Updates file.transcodedAudioPath
4. Once ready, serve video with muxed transcoded audio
5. Subsequent plays use cached audio instantly

Flow 4: Admin pre-transcodes Copy Section

1. Admin goes to Transcoding admin page
2. Sees list of files needing transcoding
3. Can click "Pre-transcode All" or individual files
4. Background job processes queue
5. Status updates shown in UI

Technical Implementation Copy Chapter

New Settings Copy Section

[settingsKey: 'FFmpeg Path', name: 'ffmpeg_path', settingsType: 'string', value: '']
[settingsKey: 'FFprobe Path', name: 'ffprobe_path', settingsType: 'string', value: '']
[settingsKey: 'Enable Audio Transcoding', name: 'transcoding_enabled', settingsType: 'boolean', value: 'false']

File Domain Changes Copy Section

class File {
  // ... existing fields ...
  String audioCodec        // detected codec (aac, eac3, ac3, dts, etc.)
  Boolean needsTranscoding // true if browser-incompatible
  String transcodedAudioPath // path to cached .aac file
}

FfmpegService Copy Section

class FfmpegService {
  // Auto-detect ffmpeg/ffprobe in PATH
  Map detectFfmpeg()

  // Probe file for audio codec
  String probeAudioCodec(String filePath)

  // Check if codec needs transcoding
  boolean needsTranscoding(String codec)

  // Transcode audio only to AAC
  String transcodeAudioToAac(String inputPath, String outputPath)

  // Mux original video with transcoded audio on-the-fly
  void streamMuxedVideo(OutputStream output, String videoPath, String audioPath, long rangeStart, long rangeEnd)
}

TranscodingService Copy Section

class TranscodingService {
  // Get cache path for file
  String getCachePath(File file)

  // Check if transcoded version exists
  boolean hasTranscodedAudio(File file)

  // Transcode file (blocking)
  File transcodeFile(File file)

  // Queue file for transcoding
  void queueForTranscoding(File file)

  // Get transcoding status
  Map getTranscodingStatus(File file)

  // Pre-transcode all pending files
  void transcodeAllPending()
}

FileController Changes Copy Section

def serve() {
  // ... existing auth checks ...

  if (file needs transcoding) {
    if (no cached audio) {
      // Return 202 with status, trigger transcoding
      return [status: 'transcoding', progress: transcodingService.getProgress(file)]
    }
    // Serve muxed video+audio
    ffmpegService.streamMuxedVideo(response.outputStream, videoPath, transcodedAudioPath, rangeStart, rangeEnd)
  } else {
    // Existing direct serve logic
  }
}

New TranscodingController Copy Section

class TranscodingController {
  // Get status of FFmpeg detection
  def status()

  // Get list of files needing transcoding
  def pending()

  // Trigger transcoding for a file
  def transcode(File file)

  // Trigger transcoding for all pending
  def transcodeAll()

  // Get progress of current transcoding
  def progress(File file)
}

Frontend Changes Copy Section

Player Service

• Check for 202 response when loading video
• Show transcoding spinner with progress
• Poll for completion
• Auto-reload video when ready

Settings UI

• New section for "Audio Transcoding"
• FFmpeg status indicator (detected/not found)
• Manual path override
• Enable/disable toggle
• Install instructions link

Admin Transcoding Page (optional)

• List of files needing transcoding
• Current queue status
• Pre-transcode button

Browser-compatible vs Incompatible Codecs Copy Chapter

Compatible (no transcoding needed):

• aac
• mp3
• opus
• vorbis
• flac

Incompatible (needs transcoding):

• eac3 (Dolby Digital Plus)
• ac3 (Dolby Digital)
• dts
• truehd
• pcm_*

FFmpeg Commands Copy Chapter

Probe audio codec:

ffprobe -v quiet -select_streams a:0 -show_entries stream=codec_name -of default=noprint_wrappers=1:nokey=1 input.mkv

Extract and transcode audio to AAC:

ffmpeg -i input.mkv -vn -c:a aac -b:a 384k output.aac

Mux video with new audio (for playback):

ffmpeg -i input.mkv -i transcoded.aac -map 0:v -map 1:a -c:v copy -c:a copy -f mp4 -movflags frag_keyframe+empty_moov pipe:1

Implementation Order Copy Chapter

1. Add File domain fields + migration
2. Create Settings entries
3. Implement FfmpegService (detect, probe, transcode)
4. Implement TranscodingService (orchestrate, cache)
5. Modify VideoService.addLocalFile to probe on attach
6. Modify FileController.serve for transcoded playback
7. Create TranscodingController
8. Add settings UI for FFmpeg config
9. Add player transcoding spinner
10. Add admin transcoding UI (optional)

--- METRICS ---

• Files Extracted: 5
• Estimated Token Budget: ~5584 tokens
• Canonical Reference: https://codewiki.google/github.com/streamaserver/streama