From 7acae8dda17c3636ff1fcfc47f29a259d76d4cdc Mon Sep 17 00:00:00 2001
From: Vanilagy <1696106+Vanilagy@users.noreply.github.com>
Date: Thu, 23 Apr 2026 11:06:50 +0200
Subject: [PATCH] Add a track disposition section to Writing HLS

---
 docs/guide/writing-hls.md | 23 +++++++++++++++++++++++
 1 file changed, 23 insertions(+)

diff --git a/docs/guide/writing-hls.md b/docs/guide/writing-hls.md
index da030a6..9da7e51 100644
--- a/docs/guide/writing-hls.md
+++ b/docs/guide/writing-hls.md
@@ -279,6 +279,29 @@ output.addAudioTrack(audioSourceDe, { languageCode: 'de', name: 'German' });
 output.addAudioTrack(audioSourceEs, { languageCode: 'es', name: 'Spanish' });
 ```
 
+### Track disposition
+
+You can control how a track is selected by players using the `disposition` option. The following fields map to HLS attributes on `#EXT-X-MEDIA`:
+- `disposition.primary` → `DEFAULT=YES` (only one per media rendition group is allowed; subsequent `primary` tracks in the same group are ignored)
+- `disposition.default` → `AUTOSELECT=YES` (also implied when `primary` is `true`)
+- `disposition.forced` → `FORCED=YES`
+
+For example:
+```ts
+output.addAudioTrack(audioSourceEn, {
+	languageCode: 'en',
+	name: 'English',
+	disposition: { primary: true },
+});
+output.addAudioTrack(audioSourceDe, {
+	languageCode: 'es',
+	name: 'Spanish',
+	disposition: { default: false },
+});
+```
+
+When unspecified, `default` is `true` and `primary` and `forced` are `false`.
+
 ### I-frame only tracks
 
 A track registered like this will be emitted via `#EXT-X-I-FRAME-STREAM-INF`: