Make transcode segment duration configurable

Author: tces1

README.md

@@ -98,6 +98,7 @@ Copy `config.example.json` and change the upstream URL:
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,
+    "segment_seconds": 2,
     "segment_retention_seconds": 300,
     "idle_timeout_seconds": 60
   }
@@ -116,6 +117,7 @@ EmbyTranscoder keeps local FFmpeg sessions tied to Emby playback check-ins:
 - `POST /Sessions/Playing` and `/Sessions/Playing/Progress` update local playback state.
 - `POST /Sessions/Playing/Stopped` immediately stops the matching local FFmpeg session.
 - HLS playlist and segment requests refresh media activity.
+- `segment_seconds` controls HLS segment duration; default `2` balances startup latency with segment count, while `1` is fastest and higher values reduce disk churn.
 - When transcoded media gets more than `buffer_pause_seconds` ahead of playback, FFmpeg is paused.
 - When buffered media falls back under `buffer_resume_seconds`, FFmpeg resumes.
 - Segments older than `segment_retention_seconds` behind the current playback position are deleted from the local cache.

config.example.json

@@ -16,6 +16,7 @@
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,
+    "segment_seconds": 2,
     "segment_retention_seconds": 300,
     "idle_timeout_seconds": 60
   },

docker/README.md

@@ -28,6 +28,7 @@ Edit `config/config.json` before startup, or copy it to `config/config.local.jso
 - startup probes VAAPI support, including device initialization and `h264_vaapi`, and fails startup when the device, driver, or ffmpeg support is unavailable
 - the image includes common Intel and AMD VAAPI userspace drivers plus `vainfo`
 - video output is capped at 1920x1080 while preserving aspect ratio
+- `transcode.segment_seconds` controls HLS segment duration; default `2` balances startup latency with segment count
 - playbackinfo rewrites prewarm the transcode session before the first playlist request
 - ffmpeg runs with low-latency startup and GOP settings to reduce first-segment delay
 - old `segment_*.ts` files are deleted once they are more than `transcode.segment_retention_seconds` behind playback

docker/config/config.json

@@ -16,6 +16,7 @@
     "max_sessions": 2,
     "buffer_pause_seconds": 300,
     "buffer_resume_seconds": 120,
+    "segment_seconds": 2,
     "segment_retention_seconds": 300,
     "idle_timeout_seconds": 60
   },

internal/config/config.go

@@ -34,10 +34,12 @@ type Transcode struct {
 	MaxSessions             int           `json:"max_sessions"`
 	BufferPauseSeconds      int           `json:"buffer_pause_seconds"`
 	BufferResumeSeconds     int           `json:"buffer_resume_seconds"`
+	SegmentSeconds          int           `json:"segment_seconds"`
 	SegmentRetentionSeconds int           `json:"segment_retention_seconds"`
 	IdleTimeoutSeconds      int           `json:"idle_timeout_seconds"`
 	BufferPause             time.Duration `json:"-"`
 	BufferResume            time.Duration `json:"-"`
+	SegmentDuration         time.Duration `json:"-"`
 	SegmentRetention        time.Duration `json:"-"`
 	IdleTimeout             time.Duration `json:"-"`
 }
@@ -93,6 +95,7 @@ func Default() Config {
 			MaxSessions:             2,
 			BufferPauseSeconds:      300,
 			BufferResumeSeconds:     120,
+			SegmentSeconds:          2,
 			SegmentRetentionSeconds: 300,
 			IdleTimeoutSeconds:      60,
 		},
@@ -152,6 +155,9 @@ func normalize(cfg *Config) {
 	if cfg.Transcode.BufferResumeSeconds <= 0 {
 		cfg.Transcode.BufferResumeSeconds = 120
 	}
+	if cfg.Transcode.SegmentSeconds <= 0 {
+		cfg.Transcode.SegmentSeconds = 2
+	}
 	if cfg.Transcode.SegmentRetentionSeconds <= 0 {
 		cfg.Transcode.SegmentRetentionSeconds = 300
 	}
@@ -160,6 +166,7 @@ func normalize(cfg *Config) {
 	}
 	cfg.Transcode.BufferPause = time.Duration(cfg.Transcode.BufferPauseSeconds) * time.Second
 	cfg.Transcode.BufferResume = time.Duration(cfg.Transcode.BufferResumeSeconds) * time.Second
+	cfg.Transcode.SegmentDuration = time.Duration(cfg.Transcode.SegmentSeconds) * time.Second
 	cfg.Transcode.SegmentRetention = time.Duration(cfg.Transcode.SegmentRetentionSeconds) * time.Second
 	cfg.Transcode.IdleTimeout = time.Duration(cfg.Transcode.IdleTimeoutSeconds) * time.Second
 }

internal/config/config_test.go

@@ -32,6 +32,9 @@ func TestDefaultConfigIsUsable(t *testing.T) {
 	if cfg.Transcode.BufferResumeSeconds != 120 {
 		t.Fatalf("buffer resume seconds = %d", cfg.Transcode.BufferResumeSeconds)
 	}
+	if cfg.Transcode.SegmentSeconds != 2 {
+		t.Fatalf("segment seconds = %d", cfg.Transcode.SegmentSeconds)
+	}
 	if cfg.Transcode.SegmentRetentionSeconds != 300 {
 		t.Fatalf("segment retention seconds = %d", cfg.Transcode.SegmentRetentionSeconds)
 	}
@@ -45,7 +48,7 @@ func TestLoadMergesJSONOverDefaults(t *testing.T) {
 	err := os.WriteFile(path, []byte(`{
 		"server": {"listen": ":9000", "debug": true},
 		"upstream": {"url": "http://emby.local:8096"},
-		"transcode": {"max_sessions": 4, "buffer_pause_seconds": 600, "buffer_resume_seconds": 90, "segment_retention_seconds": 180},
+		"transcode": {"max_sessions": 4, "buffer_pause_seconds": 600, "buffer_resume_seconds": 90, "segment_seconds": 2, "segment_retention_seconds": 180},
 		"clients": [{"name": "yamby", "match": ["Yamby"], "transcode": true}]
 	}`), 0o600)
 	if err != nil {
@@ -72,6 +75,9 @@ func TestLoadMergesJSONOverDefaults(t *testing.T) {
 	if cfg.Transcode.BufferPauseSeconds != 600 || cfg.Transcode.BufferResumeSeconds != 90 {
 		t.Fatalf("buffer thresholds = %d/%d", cfg.Transcode.BufferPauseSeconds, cfg.Transcode.BufferResumeSeconds)
 	}
+	if cfg.Transcode.SegmentSeconds != 2 {
+		t.Fatalf("segment seconds = %d", cfg.Transcode.SegmentSeconds)
+	}
 	if cfg.Transcode.SegmentRetentionSeconds != 180 {
 		t.Fatalf("segment retention seconds = %d", cfg.Transcode.SegmentRetentionSeconds)
 	}

internal/proxy/server.go

@@ -52,6 +52,7 @@ func NewWithTransport(cfg config.Config, transport http.RoundTripper) (*Server,
 		HardwareDevice:        cfg.Transcode.HardwareDevice,
 		BufferPauseThreshold:  cfg.Transcode.BufferPause,
 		BufferResumeThreshold: cfg.Transcode.BufferResume,
+		SegmentDuration:       cfg.Transcode.SegmentDuration,
 		SegmentRetention:      cfg.Transcode.SegmentRetention,
 		IdleTimeout:           cfg.Transcode.IdleTimeout,
 	})

internal/transcode/ffmpeg_args_test.go

@@ -55,14 +55,29 @@ func TestBuildFFmpegArgsAppliesLocalSeekBeforeInputAndKeepsOutputOffset(t *testi
 		t.Fatalf("expected unbounded HLS list size, args=%v", args)
 	}
 	hlsTimeIndex := slices.Index(args, "-hls_time")
-	if hlsTimeIndex < 0 || args[hlsTimeIndex+1] != "1" {
-		t.Fatalf("expected 1 second HLS segments, args=%v", args)
+	if hlsTimeIndex < 0 || args[hlsTimeIndex+1] != "2" {
+		t.Fatalf("expected default HLS segment duration, args=%v", args)
 	}
 	if args[len(args)-1] != filepath.Join(session.Dir, "master.m3u8") {
 		t.Fatalf("playlist output = %q", args[len(args)-1])
 	}
 }
 
+func TestBuildFFmpegArgsUsesConfiguredSegmentDuration(t *testing.T) {
+	session := &Session{
+		ID:           "item123",
+		Dir:          t.TempDir(),
+		SegmentTicks: 2 * timeSecondTicks,
+	}
+
+	args := buildFFmpegArgs(session, Request{InputURL: "http://upstream/stream"})
+
+	hlsTimeIndex := slices.Index(args, "-hls_time")
+	if hlsTimeIndex < 0 || args[hlsTimeIndex+1] != "2" {
+		t.Fatalf("expected configured HLS segment duration, args=%v", args)
+	}
+}
+
 func TestBuildFFmpegArgsDoesNotThrottleInputWithRealtimeFlag(t *testing.T) {
 	session := &Session{
 		ID:             "item123",

internal/transcode/handler.go

@@ -49,7 +49,7 @@ func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		logging.Infof("playlist request id=%s start_ticks=%d", id, startTimeTicksFromRawQuery(r.URL.RawQuery))
 		traceSwitch("playlist_request id=%s start_ticks=%d query=%s elapsed=%s", id, startTimeTicksFromRawQuery(r.URL.RawQuery), redactURLString("?"+r.URL.RawQuery), time.Since(requestStarted))
 		if info, known := h.Manager.MediaInfo(id); known {
-			if playlist, ready := VirtualVODPlaylist(info, defaultSegmentTicks, r.URL.RawQuery); ready {
+			if playlist, ready := VirtualVODPlaylist(info, h.Manager.segmentTicks(), r.URL.RawQuery); ready {
 				logging.Infof("playlist virtual id=%s duration=%s", id, formatTicks(info.RunTimeTicks))
 				traceSwitch("playlist_virtual id=%s duration=%s start_ticks=%d query=%s media=%s elapsed=%s", id, formatTicks(info.RunTimeTicks), startTimeTicksFromRawQuery(r.URL.RawQuery), redactURLString("?"+r.URL.RawQuery), info.Summary(), time.Since(requestStarted))
 				w.Header().Set("Content-Type", "application/vnd.apple.mpegurl")
@@ -138,14 +138,15 @@ func (h Handler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 }
 
 func (h Handler) sessionForSegment(id string, segmentIndex int, name string, r *http.Request, requestStarted time.Time) (*Session, error) {
-	segmentReq := requestWithSegmentStart(r, segmentIndex)
+	segmentReq := requestWithSegmentStart(r, segmentIndex, h.Manager.segmentTicks())
 	inputURL := ""
 	if h.InputURLForID != nil {
 		inputURL = h.InputURLForID(id, segmentReq)
 	}
 	request := requestFromHTTP(id, inputURL, segmentReq)
 	request.SegmentStartIndex = segmentIndex
 	request.SegmentRequest = true
+	request.SegmentTicks = h.Manager.segmentTicks()
 	request.RequestedStartTimeTicks = int64Query(r.URL.Query().Get("StartTimeTicks"))
 	if request.RequestedStartTimeTicks == 0 {
 		request.RequestedStartTimeTicks = request.StartTimeTicks
@@ -223,27 +224,30 @@ func segmentInputFingerprint(raw string) string {
 	return parsed.String()
 }
 
-func requestWithSegmentStart(r *http.Request, segmentIndex int) *http.Request {
+func requestWithSegmentStart(r *http.Request, segmentIndex int, segmentTicks int64) *http.Request {
 	req := r.Clone(r.Context())
 	u := *r.URL
 	query := u.Query()
-	query.Set("StartTimeTicks", strconv.FormatInt(segmentStartTicksFromRequest(r, segmentIndex), 10))
+	query.Set("StartTimeTicks", strconv.FormatInt(segmentStartTicksFromRequest(r, segmentIndex, segmentTicks), 10))
 	query.Del("runtimeTicks")
 	query.Del("actualSegmentLengthTicks")
 	u.RawQuery = query.Encode()
 	req.URL = &u
 	return req
 }
 
-func segmentStartTicksFromRequest(r *http.Request, segmentIndex int) int64 {
+func segmentStartTicksFromRequest(r *http.Request, segmentIndex int, segmentTicks int64) int64 {
 	if raw := r.URL.Query().Get("runtimeTicks"); raw != "" {
 		return int64Query(raw)
 	}
-	return segmentStartTicks(segmentIndex)
+	return segmentStartTicks(segmentIndex, segmentTicks)
 }
 
-func segmentStartTicks(segmentIndex int) int64 {
-	return int64(segmentIndex) * defaultSegmentTicks
+func segmentStartTicks(segmentIndex int, segmentTicks int64) int64 {
+	if segmentTicks <= 0 {
+		segmentTicks = defaultSegmentTicks
+	}
+	return int64(segmentIndex) * segmentTicks
 }
 
 func removeLocalAndPlaybackOnlyQuery(query url.Values) {

internal/transcode/manager.go

@@ -35,6 +35,7 @@ type Options struct {
 	HardwareDevice        string
 	BufferPauseThreshold  time.Duration
 	BufferResumeThreshold time.Duration
+	SegmentDuration       time.Duration
 	SegmentRetention      time.Duration
 	BufferCheckInterval   time.Duration
 	IdleTimeout           time.Duration
@@ -55,6 +56,7 @@ type Request struct {
 	RequestedStartTimeTicks int64
 	SegmentStartIndex       int
 	SegmentRequest          bool
+	SegmentTicks            int64
 	Media                   MediaInfo
 }
 
@@ -77,6 +79,7 @@ type Session struct {
 	SegmentStartIndex       int
 	OldestSegmentKept       int
 	HighestSegmentSeen      int
+	SegmentTicks            int64
 	Media                   MediaInfo
 	Dir                     string
 	InputURL                string
@@ -158,6 +161,9 @@ func normalizeManagerOptions(options Options) Options {
 	if options.BufferResumeThreshold <= 0 {
 		options.BufferResumeThreshold = 2 * time.Minute
 	}
+	if options.SegmentDuration <= 0 {
+		options.SegmentDuration = 2 * time.Second
+	}
 	if options.SegmentRetention <= 0 {
 		options.SegmentRetention = 5 * time.Minute
 	}
@@ -178,6 +184,38 @@ func normalizeManagerOptions(options Options) Options {
 	return options
 }
 
+func (m *Manager) segmentTicks() int64 {
+	if m == nil {
+		return defaultSegmentTicks
+	}
+	return segmentTicksFromDuration(m.options.SegmentDuration)
+}
+
+func segmentTicksFromDuration(duration time.Duration) int64 {
+	ticks := durationToTicks(duration)
+	if ticks <= 0 {
+		return defaultSegmentTicks
+	}
+	return ticks
+}
+
+func sessionSegmentTicks(session *Session) int64 {
+	if session == nil || session.SegmentTicks <= 0 {
+		return defaultSegmentTicks
+	}
+	return session.SegmentTicks
+}
+
+func hlsTimeValue(segmentTicks int64) string {
+	if segmentTicks <= 0 {
+		segmentTicks = defaultSegmentTicks
+	}
+	if segmentTicks%timeSecondTicks == 0 {
+		return strconv.FormatInt(segmentTicks/timeSecondTicks, 10)
+	}
+	return strconv.FormatFloat(ticksFloatSeconds(segmentTicks), 'f', 3, 64)
+}
+
 type MediaInfo struct {
 	ItemID        string
 	SourceID      string
@@ -349,6 +387,7 @@ func (m *Manager) Ensure(id string, request Request) (*Session, error) {
 		}
 		ctx, cancel := context.WithCancel(context.Background())
 		session := &Session{ID: id, Dir: dir, InputURL: request.InputURL, LastAccess: now, LastMediaAccess: now, cancel: cancel}
+		session.SegmentTicks = m.segmentTicks()
 		touchSession(session, request, now, true)
 		if session.Media.IsZero() {
 			session.Media = m.media[id]
@@ -587,6 +626,12 @@ func touchSession(session *Session, request Request, now time.Time, mediaAccess
 	session.StartTimeTicks = request.StartTimeTicks
 	session.RequestedStartTimeTicks = request.RequestedStartTimeTicks
 	session.SegmentStartIndex = request.SegmentStartIndex
+	if request.SegmentTicks > 0 {
+		session.SegmentTicks = request.SegmentTicks
+	}
+	if session.SegmentTicks <= 0 {
+		session.SegmentTicks = defaultSegmentTicks
+	}
 	if session.OldestSegmentKept < request.SegmentStartIndex {
 		session.OldestSegmentKept = request.SegmentStartIndex
 	}
@@ -625,7 +670,7 @@ func (m *Manager) segmentCleanupTaskLocked(session *Session) (segmentCleanupTask
 		return segmentCleanupTask{}, false
 	}
 	cutoffTicks := session.PositionTicks - retentionTicks
-	beforeSegment := int(cutoffTicks / defaultSegmentTicks)
+	beforeSegment := int(cutoffTicks / sessionSegmentTicks(session))
 	if beforeSegment <= session.OldestSegmentKept {
 		return segmentCleanupTask{}, false
 	}
@@ -679,7 +724,7 @@ func (m *Manager) bufferActionLocked(session *Session) (bufferAction, bool) {
 	}
 	generatedTicks := baseTicks
 	if session.HighestSegmentSeen >= session.SegmentStartIndex {
-		generatedTicks += int64(session.HighestSegmentSeen-session.SegmentStartIndex+1) * defaultSegmentTicks
+		generatedTicks += int64(session.HighestSegmentSeen-session.SegmentStartIndex+1) * sessionSegmentTicks(session)
 	}
 	playedTicks := session.PositionTicks
 	if playedTicks < baseTicks {
@@ -1211,7 +1256,7 @@ func buildFFmpegArgs(session *Session, request Request, options ...FFmpegOptions
 	}
 	args = append(args,
 		"-f", "hls",
-		"-hls_time", "1",
+		"-hls_time", hlsTimeValue(sessionSegmentTicks(session)),
 		"-hls_list_size", "0",
 		"-hls_flags", "independent_segments",
 		"-start_number", strconv.Itoa(session.SegmentStartIndex),