How Transcoding works? - Streamit Laravel - Documentation

1. Overview

Transcoding converts a raw video file uploaded to an episode into a multi-quality streaming format (HLS) that plays smoothly on any device and network speed, without the viewer downloading the full file first.

Everything runs on your own server — there is no third-party transcoding service, subscription, or API key involved. The Short Drama add-on ships with its own processing pipeline built on FFmpeg, so once it’s configured, transcoding happens automatically every time an admin uploads a local video file.

2. Key Highlights

Automatic, no manual encoding. Admins upload a video; the server generates a ready-to-stream package in the background.
Multiple quality levels. Every episode is encoded into 480p, 720p, and 1080p renditions, so the player can switch quality based on the viewer’s connection.
Vertical video done right. Portrait (9:16) short-drama footage is detected automatically and encoded at the correct orientation, instead of being stretched or letterboxed into landscape.
Wide device compatibility. Output is normalized to a color format every phone, browser, and smart TV can hardware-decode, avoiding black-screen playback failures some source files would otherwise cause.
Server-aware processing. The pipeline checks how much CPU the server actually has (including on shared/containerized hosting) and paces itself — small servers process one video at a time instead of overloading.
Never blocks the admin panel. Encoding runs as a background job. Admins can keep working while a video processes; the episode goes live automatically once it’s ready.
Graceful fallback. If a viewer opens an episode while it’s still processing, the original uploaded file is served directly so it’s still watchable, then automatically upgraded to the full adaptive stream once processing finishes.

3. How It Works

1. Upload. An admin uploads a video file to an episode and enables transcoding.

2. Analyze. The server inspects the source file — resolution, orientation (portrait/landscape), and any audio or subtitle tracks embedded in the file.

3. Encode. FFmpeg produces three quality renditions of the video (480p / 720p / 1080p), each split into small streaming segments.

4. Package. If multi-language audio or subtitles are enabled, those are processed and linked in as separate selectable tracks.

5. Generate previews. Poster images, thumbnails, and (if enabled) scrub-bar preview images are extracted from the video.

6. Build the playlist. All renditions and tracks are compiled into a single streaming playlist file (master.m3u8) that the player reads to know which qualities and tracks are available.

7. Publish. The episode is automatically marked active and becomes playable — no manual “publish” step required.

While processing is underway, the episode stays hidden from viewers; a status indicator in the admin panel shows progress until it completes.

4. Setup & Server Configuration

4.1 Admin workflow

1. Go to Short Drama → Episodes → Create (or edit an existing episode).

2. Set Upload Type to Local, and select the video file.

3. Under Processing Options, enable:

Enable transcoding (HLS) — generates the 480p / 720p / 1080p stream.
Enable multi-audio — auto-detects and includes embedded audio tracks.
Enable subtitle support — auto-detects and includes embedded subtitle tracks.

4. Save the episode.[Screenshot: Episode → Processing options panel with transcoding toggle enabled]

5. The episode shows a Processing status badge. Leave it — no further action is needed.[Screenshot: Episode list showing a processing status badge]

6. Once the badge changes to Completed, the episode is live and streamable.

4.2 Server requirements

Requirement	Recommendation
OS	Ubuntu 20.04/22.04 LTS (or any Linux distribution FFmpeg supports)
FFmpeg	Version 4.3 or newer (available system-wide on standard PATH)
CPU	4+ cores minimum; 8+ cores recommended for a production launch
RAM	8 GB minimum; 16 GB+ recommended
Disk	Fast SSD/NVMe for temporary processing files
PHP	8.2+, with `pdo`, `mbstring`, `openssl`, `json`, `fileinfo`, `xml`, `curl`, `zip`, `gd`
Queue	A persistent queue driver — `database` or `redis` (never `sync`)
Process manager	Supervisor (or systemd) to keep the queue worker running continuously

Transcoding is CPU-intensive. For higher traffic launches, run the queue worker on a separate server from the one serving web traffic.

4.3 Installing FFmpeg

Install FFmpeg so that ffmpeg and ffprobe are available on your server’s standard system PATH:

sudo apt update
sudo apt install ffmpeg
ffmpeg -version
ffprobe -version

4.4 Environment configuration

Add the following to your project’s .env file:

QUEUE_CONNECTION=database
SHORT_DRAMA_PROCESSING_QUEUE=default

Run the queue worker (this is what actually performs the encoding):

php artisan queue:work --queue=default --timeout=3600 --tries=3

sudo apt install supervisor
sudo supervisorctl reread
sudo supervisorctl update
sudo supervisorctl start short-drama-worker:*

After changing .env, restart the worker and clear the cached config:

php artisan config:clear
sudo supervisorctl 
restart short-drama-worker:*

Built-in Fallback Worker: If no persistent queue worker is active, the add-on briefly spawns a temporary background worker on dispatch. This is intended for local testing only — disable it in production once Supervisor is active by setting SHORT_DRAMA_AUTO_WORKER=false.

4.5 Verifying the setup

A built-in check command confirms FFmpeg, storage, and the queue are all working:

bashphp artisan short-drama:verify-local-env --hls-smoke --queue-smoke

5. Configuration Settings

Setting (`.env` key)	Default	Description
`SHORT_DRAMA_PROCESSING_QUEUE`	`default`	Queue name on which transcoding jobs run.
`FFMPEG_THREADS`	auto	CPU threads dedicated per encode job. Left unset, it auto-detects based on available CPU cores.
`SHORT_DRAMA_MAX_CONCURRENT`	auto	How many episodes may transcode at the same time. Left unset, smaller hosts are limited to 1 at a time to prevent CPU starvation.
`SHORT_DRAMA_SLOT_RETRY_DELAY`	`30` (seconds)	How long a queued job waits before retrying when all processing slots are busy.
`SHORT_DRAMA_RETRY_WINDOW_HOURS`	`24`	How long a job keeps retrying for a free processing slot before giving up.
`SHORT_DRAMA_AUTO_WORKER`	`true`	Auto-starts a temporary worker if none is running. Set to `false` once Supervisor manages a permanent worker.
`SHORT_DRAMA_RAW_SOURCE_FALLBACK`	`true`	Serves the original upload directly if a viewer opens the episode before transcoding finishes.

Quality levels and target bitrates are set in the module configuration:

Quality	Target Bitrate	Resolution & FPS
480p	1000 Kbps	854×480 @ 24fps
720p	2500 Kbps	1280×720 @ 24fps
1080p	4500 Kbps	1920×1080 @ 24fps

6. Limitations & Notes

Requires a VPS or dedicated server with FFmpeg and a persistent queue worker. Not supported on shared hosting
Transcoding only applies to locally uploaded video files. Episodes set to URL upload type stream directly from the source you provide and are not re-encoded.
Storage grows roughly 3x the size of the original file once all quality levels are generated — plan disk space (or object storage) accordingly.
The queue must use a persistent driver (database or redis). Using sync will make the admin panel hang while a video encodes.
Long or large uploads need a queue timeout of at least 3600 seconds (--timeout=3600).
This module produces HLS streams (.m3u8 / .ts). It does not generate DASH (.mpd) manifests.
FFmpeg process management and queue logic are fully integrated; no separate subscriptions or paid external API keys are required.

Conclusion

Transcoding turns any uploaded video into a smooth, adaptive-quality stream automatically, on infrastructure you control. Once FFmpeg is installed on your server and a persistent queue worker is configured, admins simply upload local video files and enable transcoding — the system takes care of encoding, packaging, and publishing seamless HLS streams for your viewers.