yhlhoh/live
1
0 Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

feat: encode on the GPU and restart individual renditions

Browse Source 
Hardware encoding
- Detect the best usable encoder at startup by encoding a test frame with each
  candidate in turn (nvenc, qsv, amf, then libx264). Being compiled into ffmpeg
  is not enough: h264_amf fails without amfrt64.dll and h264_qsv fails without an
  Intel iGPU, so the probe is the only reliable answer.
- Translate the quality target into the chosen encoder's own vocabulary. libx264's
  -crf and "ultrafast" mean nothing to h264_nvenc, which takes -cq and p1..p7, so
  passing the configured values straight through would have been silently wrong.
- On the reference GTX 1060 a 1080p->720p rendition costs ~62% of a core on NVENC
  versus ~109% on libx264 ultrafast.

Per-rendition supervision
- Track encoder processes per rendition, not per stream. is_running answered
  "any alive", so when the source ("原画") encoder died while 1080p and 720p kept
  running, the supervisor saw a healthy stream and never restarted it — the
  source URL then 404'd permanently. It now requires every rendition to be alive
  and reports which ones are down.
- Restart only the dead renditions, so a single failure no longer interrupts
  viewers on the renditions that were fine.

Production serving
- Serve the built frontend from FastAPI with SPA fallback, so production is one
  process and one port with no Node runtime. Node becomes a build-time dependency.
- start.ps1/start.sh build the frontend on first run instead of failing to a 503.

Cleanup
- Drop the duplicated top-left LIVE badge; the control strip already carries it.

Co-Authored-By: Claude Opus 4.8 (1M context) <[email protected]>
This commit is contained in:
adminandClaude Opus 4.8 committed 2026-09-27 18:56:21 +08:00
1 parent 996e3fea39
commit 4ee945ca0d
7 files changed
+394 -111
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

backend/services/hardware.py
+117
View File
@@ -0,0 +1,117 @@
"""Pick the best available video encoder for the host.
Transcoding on the CPU is the fallback, not the default: a GPU encoder handles the
same ladder at a fraction of the CPU and leaves the cores free for the rest of the
server. Which encoder is usable cannot be decided from `ffmpeg -encoders` alone —
that lists everything the *build* supports, and a build with nvenc, amf and qsv
compiled in still fails at runtime on a machine with the wrong hardware (no NVIDIA
card, no Intel iGPU, a missing amfrt64.dll). So each candidate is probed by
actually encoding a frame.
The result is cached: probing costs a subprocess per candidate, and the answer
cannot change while the process is running.
"""
from __future__ import annotations
import subprocess
from dataclasses import dataclass
@dataclass(frozen=True)
class Encoder:
"""A usable ffmpeg video encoder plus the flags that suit it."""
name: str
# True when the encoder came from hardware rather than the CPU.
hardware: bool
# ffmpeg `-preset` value, already mapped to this encoder's own scale.
preset: str
# How a quality target is expressed for this encoder.
quality_flag: str # "-crf" or "-cq"
quality_value: int
# Value that means "encode every frame" for -sc_threshold where it applies.
supports_sc_threshold: bool
# Ranked by preference. nvenc is the only one that realistically serves this
# project today, but the others cost nothing to try and make the code portable to
# an Intel or AMD host.
# rate-control / preset translation between the software encoders and each family.
# The libraries share almost no vocabulary: libx264's -crf 23 is not h264_nvenc's
# -cq 23, and "ultrafast" is not a value nvenc accepts at all.
_SOFTWARE = {
"libx264": ("-crf", 23, "ultrafast"),
"libx265": ("-crf", 28, "ultrafast"),
}
_CANDIDATES = [
# (encoder, hardware, quality flag, quality value, preset, honours -sc_threshold)
("h264_nvenc", True, "-cq", 26, "p1", False),
("hevc_nvenc", True, "-cq", 28, "p1", False),
("h264_qsv", True, "-global_quality", 26, "veryfast", False),
("h264_amf", True, "-qp_i", 26, "speed", False),
("libx264", False, "-crf", 23, "ultrafast", True),
]
_cache: Encoder | None = None
_probe_log: list[str] = []
def _probe(encoder: str, quality_flag: str, quality_value: int, preset: str, sc_threshold: bool) -> bool:
"""Encode one synthetic frame; the only reliable test of "does this work here"."""
cmd = [
"ffmpeg", "-hide_banner", "-loglevel", "error",
"-f", "lavfi", "-i", "testsrc=size=320x240:rate=25",
"-frames:v", "5",
"-c:v", encoder,
]
if preset:
cmd += ["-preset", preset]
cmd += [quality_flag, str(quality_value)]
if sc_threshold:
cmd += ["-sc_threshold", "0"]
cmd += ["-f", "null", "-"]
try:
result = subprocess.run(cmd, capture_output=True, timeout=30)
except (OSError, subprocess.SubprocessError):
return False
return result.returncode == 0
def detect_encoder() -> Encoder:
"""Return the highest-priority encoder that actually works on this host."""
global _cache
if _cache is not None:
return _cache
for name, hardware, quality_flag, quality_value, preset, sc_threshold in _CANDIDATES:
if _probe(name, quality_flag, quality_value, preset, sc_threshold):
_cache = Encoder(name, hardware, preset, quality_flag, quality_value, sc_threshold)
if hardware:
print(f"[transcoder] hardware encoder: {name}", flush=True)
else:
print(
f"[transcoder] no working hardware encoder; falling back to {name} "
f"(probed: {', '.join(_probe_log)})",
flush=True,
)
return _cache
_probe_log.append(name)
# libx264 ships in every ffmpeg build; reaching here means ffmpeg is missing.
_cache = Encoder("libx264", False, "ultrafast", "-crf", 23, True)
return _cache
def clear_encoder_cache() -> None:
"""Forget the probe result (used by tests)."""
global _cache
_cache = None
_probe_log.clear()
def probe_report() -> list[str]:
"""Encoders that were tried and rejected, in order."""
return list(_probe_log)
backend/services/transcoder.py
+160 -89
View File
@@ -1,34 +1,66 @@
import subprocess
import os
from dataclasses import dataclass
from config import settings
from services.hardware import detect_encoder
def _rendition_slug(quality: dict) -> str:
"""Path slug for a rendition, falling back to its label."""
return quality.get("path") or quality["label"]
@dataclass
class _Rendition:
"""One encoder process, remembered per rendition rather than per stream."""
slug: str
process: subprocess.Popen
class TranscodeManager:
_processes: dict[str, list[subprocess.Popen]] = {}
# Keyed by stream, then by rendition slug. Per-rendition tracking is what lets
# a single dead encoder be noticed: a stream-level list made a dead 原画
# invisible as long as any sibling encoder was still alive.
_renditions: dict[str, dict[str, _Rendition]] = {}
# Signature of the last successful start, so a supervisor can tell whether a
# running set of processes still matches the stream's current configuration.
_signatures: dict[str, str] = {}
# Number of renditions that failed to launch on the last attempt.
_failed_starts: dict[str, int] = {}
@staticmethod
def _signature(qualities: list[dict]) -> str:
# The hardware encoder is part of the signature: if detection ever changes
# (a driver appears, the GPU is removed), running processes are stale.
encoder = detect_encoder().name
return "|".join(
f"{q.get('label')}:{q.get('width')}x{q.get('height')}:{q.get('bitrate')}:"
f"{'copy' if q.get('copy') else q.get('codec', 'libx264')}"
f"{'copy' if q.get('copy') else encoder}"
for q in qualities
)
def is_running(self, stream_key: str) -> bool:
"""True when at least one transcode process exists and none have exited."""
procs = self._processes.get(stream_key)
if not procs:
return False
return any(proc.poll() is None for proc in procs)
"""True when every rendition this stream should have is still alive."""
return not self.dead_renditions(stream_key)
def dead_renditions(self, stream_key: str) -> list[str]:
"""Slugs of renditions that have exited. Empty when all are healthy.
Missing sessions count as dead, so a stream that was never started
reports every rendition as needing one.
"""
renditions = self._renditions.get(stream_key)
if not renditions:
return ["*"]
return [slug for slug, r in renditions.items() if r.process.poll() is not None]
def needs_restart(self, stream_key: str, qualities: list[dict]) -> bool:
if not qualities:
return False
return self._signatures.get(stream_key) != self._signature(qualities) or not self.is_running(stream_key)
if self._signatures.get(stream_key) != self._signature(qualities):
return True
return bool(self.dead_renditions(stream_key))
def _clear_stale_output(self, hls_dir: str) -> None:
"""Drop the previous run's playlist and segments.
@@ -51,95 +83,134 @@ class TranscodeManager:
pass
def start_transcode(self, stream_key: str, input_url: str, qualities: list[dict]):
if stream_key in self._processes and self.is_running(stream_key):
return
self.stop_transcode(stream_key)
"""Start whichever renditions are not already alive.
procs = []
Restarting only the dead ones keeps the survivors streaming: tearing down
every encoder because one of them exited would black out the whole stream,
and a viewer on a healthy rendition has no reason to be interrupted.
"""
signature = self._signature(qualities)
if self._signatures.get(stream_key) != signature:
# The configuration changed, so nothing on disk is known-good.
self.stop_transcode(stream_key)
else:
self._reap_dead(stream_key)
live = self._renditions.setdefault(stream_key, {})
started = 0
segment_seconds = max(1, settings.hls_segment_seconds)
for quality in qualities:
label = quality["label"]
# The stream-copy ("原画") rendition carries the top rendition's numbers
# only so the signature stays complete; ffmpeg copies the input rather
# than encoding to them. See StreamService.transcode_renditions.
is_copy = bool(quality.get("copy"))
# Files land under the rendition's path slug, never its label: MediaMTX
# refuses non-alphanumeric HLS paths and the label may be Chinese.
path_slug = quality.get("path") or label
width = quality["width"]
height = quality["height"]
fps = quality.get("fps", 30)
codec = quality.get("codec", "libx264")
bitrate = quality["bitrate"]
crf = quality.get("crf", 23)
preset = quality.get("preset", "ultrafast")
audio_bitrate = quality.get("audio_bitrate", "128k")
keyframe_seconds = quality.get("keyframe_seconds", segment_seconds)
keyframe_frames = keyframe_seconds * fps
hls_dir = os.path.join(settings.hls_runtime_dir, stream_key, path_slug)
os.makedirs(hls_dir, exist_ok=True)
self._clear_stale_output(hls_dir)
hls_output = [
"-f", "hls",
"-hls_time", str(segment_seconds),
"-hls_list_size", "6",
"-hls_flags", "delete_segments+independent_segments+program_date_time",
"-hls_segment_filename", os.path.join(hls_dir, "segment_%03d.ts"),
os.path.join(hls_dir, "index.m3u8"),
]
# NOTE: ffmpeg's -reconnect* flags are HTTP/HTTPS-only protocol
# options and make RTMP inputs fail with "Option not found".
# RTMP drop recovery is handled by the supervisor in main.py,
# which restarts exited encoders on its next tick.
hls_input = ["-rw_timeout", "10000000", "-i", input_url]
if is_copy:
# Source ("原画") rendition: keep the publisher's video as-is and only
# re-wrap it, so the output keeps the exact incoming resolution,
# frame rate and bitrate. Video copy costs no CPU; audio is re-encoded
# because MPEG-TS cannot carry every codec a publisher might send, and
# one AAC track is a rounding error next to the video encoders.
cmd = (
["ffmpeg", "-y"] + hls_input
+ [
"-c:v", "copy",
"-c:a", "aac", "-b:a", "192k",
"-copyts", "-start_at_zero",
"-map", "0:v:0", "-map", "0:a:0?",
]
+ hls_output
)
else:
cmd = (
["ffmpeg", "-y"] + hls_input
+ [
"-c:v", codec, "-preset", preset,
"-r", str(fps), "-b:v", bitrate, "-crf", str(crf),
"-s", f"{width}x{height}",
"-sc_threshold", "0",
"-g", str(keyframe_frames),
"-keyint_min", str(keyframe_frames),
"-force_key_frames", f"expr:gte(t,n_forced*{keyframe_seconds})",
"-copyts", "-start_at_zero",
"-c:a", "aac", "-b:a", audio_bitrate,
]
+ hls_output
)
slug = _rendition_slug(quality)
if slug in live:
continue # still running; leave it alone
cmd = self._build_command(stream_key, quality, input_url, segment_seconds)
try:
proc = subprocess.Popen(
cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL
)
procs.append(proc)
proc = subprocess.Popen(cmd, stdout=subprocess.DEVNULL, stderr=subprocess.DEVNULL)
except FileNotFoundError:
pass
continue
live[slug] = _Rendition(slug=slug, process=proc)
started += 1
self._processes[stream_key] = procs
self._signatures[stream_key] = self._signature(qualities)
self._failed_starts[stream_key] = 0 if procs else self._failed_starts.get(stream_key, 0) + 1
self._signatures[stream_key] = signature
self._failed_starts[stream_key] = max(0, len(qualities) - len(live))
return started
def _reap_dead(self, stream_key: str) -> None:
"""Forget exited renditions so the next start can replace them."""
live = self._renditions.get(stream_key)
if not live:
return
for slug, rendition in list(live.items()):
if rendition.process.poll() is not None:
del live[slug]
def _build_command(self, stream_key: str, quality: dict, input_url: str, segment_seconds: int) -> list[str]:
label = quality["label"]
# The stream-copy ("原画") rendition carries the top rendition's numbers
# only so the signature stays complete; ffmpeg copies the input rather
# than encoding to them. See StreamService.transcode_renditions.
is_copy = bool(quality.get("copy"))
# Files land under the rendition's path slug, never its label: MediaMTX
# refuses non-alphanumeric HLS paths and the label may be Chinese.
path_slug = _rendition_slug(quality)
width = quality["width"]
height = quality["height"]
fps = quality.get("fps", 30)
codec = quality.get("codec", "libx264")
bitrate = quality["bitrate"]
crf = quality.get("crf", 23)
preset = quality.get("preset", "ultrafast")
audio_bitrate = quality.get("audio_bitrate", "128k")
keyframe_seconds = quality.get("keyframe_seconds", segment_seconds)
keyframe_frames = keyframe_seconds * fps
hls_dir = os.path.join(settings.hls_runtime_dir, stream_key, path_slug)
os.makedirs(hls_dir, exist_ok=True)
self._clear_stale_output(hls_dir)
hls_output = [
"-f", "hls",
"-hls_time", str(segment_seconds),
"-hls_list_size", "6",
"-hls_flags", "delete_segments+independent_segments+program_date_time",
"-hls_segment_filename", os.path.join(hls_dir, "segment_%03d.ts"),
os.path.join(hls_dir, "index.m3u8"),
]
# NOTE: ffmpeg's -reconnect* flags are HTTP/HTTPS-only protocol
# options and make RTMP inputs fail with "Option not found".
# RTMP drop recovery is handled by the supervisor in main.py,
# which restarts exited encoders on its next tick.
hls_input = ["-rw_timeout", "10000000", "-i", input_url]
if is_copy:
# Source ("原画") rendition: keep the publisher's video as-is and only
# re-wrap it, so the output keeps the exact incoming resolution,
# frame rate and bitrate. Video copy costs no CPU; audio is re-encoded
# because MPEG-TS cannot carry every codec a publisher might send, and
# one AAC track is a rounding error next to the video encoders.
return (
["ffmpeg", "-y"] + hls_input
+ [
"-c:v", "copy",
"-c:a", "aac", "-b:a", "192k",
"-copyts", "-start_at_zero",
"-map", "0:v:0", "-map", "0:a:0?",
]
+ hls_output
)
# Encode on the GPU when the host has one. The configured codec/preset
# describe the *intended* quality, but the values themselves are
# encoder-specific: libx264's -crf and "ultrafast" mean nothing to
# h264_nvenc, which wants -cq and p1..p7. So the target is re-expressed
# in the chosen encoder's own terms rather than passed through.
encoder = detect_encoder()
encode_args = ["-c:v", encoder.name]
if encoder.name == codec:
# The configured encoder is the one we picked: honour its settings.
encode_args += ["-preset", preset, encoder.quality_flag, str(crf)]
else:
encode_args += ["-preset", encoder.preset, encoder.quality_flag, str(encoder.quality_value)]
if encoder.supports_sc_threshold:
# Only the software encoders take this; nvenc rejects it.
encode_args += ["-sc_threshold", "0"]
return (
["ffmpeg", "-y"] + hls_input
+ encode_args
+ [
"-r", str(fps), "-b:v", bitrate,
"-s", f"{width}x{height}",
"-g", str(keyframe_frames),
"-keyint_min", str(keyframe_frames),
"-force_key_frames", f"expr:gte(t,n_forced*{keyframe_seconds})",
"-copyts", "-start_at_zero",
"-c:a", "aac", "-b:a", audio_bitrate,
]
+ hls_output
)
def stop_transcode(self, stream_key: str):
procs = self._processes.pop(stream_key, [])
for proc in procs:
live = self._renditions.pop(stream_key, {})
for rendition in live.values():
proc = rendition.process
try:
proc.terminate()
proc.wait(timeout=5)
@@ -150,7 +221,7 @@ class TranscodeManager:
pass
def stop_all(self):
for key in list(self._processes.keys()):
for key in list(self._renditions.keys()):
self.stop_transcode(key)