@norskvideo/ctl-dev-kit 0.2.114 → 0.2.116

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
@@ -63,6 +63,9 @@ jobs:
63
63
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
64
64
  mkdir -p "$base"
65
65
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
66
+ # The shared asset cache (sample media), kept across runs: under the work
67
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
68
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
66
69
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
67
70
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
68
71
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -119,6 +122,9 @@ jobs:
119
122
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
120
123
  mkdir -p "$base"
121
124
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
125
+ # The shared asset cache (sample media), kept across runs: under the work
126
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
127
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
122
128
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
123
129
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
124
130
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -100,6 +100,9 @@ jobs:
100
100
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
101
101
  mkdir -p "$base"
102
102
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
103
+ # The shared asset cache (sample media), kept across runs: under the work
104
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
105
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
103
106
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
104
107
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
105
108
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -199,6 +202,9 @@ jobs:
199
202
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
200
203
  mkdir -p "$base"
201
204
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
205
+ # The shared asset cache (sample media), kept across runs: under the work
206
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
207
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
202
208
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
203
209
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
204
210
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -332,6 +338,9 @@ jobs:
332
338
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
333
339
  mkdir -p "$base"
334
340
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
341
+ # The shared asset cache (sample media), kept across runs: under the work
342
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
343
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
335
344
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
336
345
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
337
346
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -564,6 +573,9 @@ jobs:
564
573
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
565
574
  mkdir -p "$base"
566
575
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
576
+ # The shared asset cache (sample media), kept across runs: under the work
577
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
578
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
567
579
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
568
580
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
569
581
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -774,6 +786,9 @@ jobs:
774
786
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
775
787
  mkdir -p "$base"
776
788
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
789
+ # The shared asset cache (sample media), kept across runs: under the work
790
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
791
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
777
792
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
778
793
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
779
794
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -886,6 +901,9 @@ jobs:
886
901
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
887
902
  mkdir -p "$base"
888
903
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
904
+ # The shared asset cache (sample media), kept across runs: under the work
905
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
906
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
889
907
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
890
908
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
891
909
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -1025,6 +1043,9 @@ jobs:
1025
1043
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
1026
1044
  mkdir -p "$base"
1027
1045
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
1046
+ # The shared asset cache (sample media), kept across runs: under the work
1047
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
1048
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
1028
1049
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
1029
1050
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
1030
1051
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -36,6 +36,9 @@ on:
36
36
 
37
37
  permissions:
38
38
  contents: read
39
+ # GitHub Packages needs a token even to read norsk's dev packages (the
40
+ # dev SDK lane below).
41
+ packages: read
39
42
 
40
43
  jobs:
41
44
  drift:
@@ -198,6 +201,16 @@ jobs:
198
201
  with:
199
202
  clean: true
200
203
  - name: Lint + typecheck + unit tests
204
+ env:
205
+ # The dev SDK lane, for a repo that opts in with .github/ci/sdk-dev.sh
206
+ # (norsk-relay): after the frozen install, the norsk SDKs are
207
+ # reinstalled from norsk's dev packages (every green push to norsk
208
+ # main, on GitHub Packages), so typecheck and unit run against norsk
209
+ # as it is now, not the nightly the tree pins -- a change that needs
210
+ # a norsk change merged this morning is green today. Not for a bot
211
+ # PR: a bump is asking about its pin. The committed pins are untouched.
212
+ SDK_LANE: ${{ (github.event_name == 'pull_request' && (github.head_ref == 'bump/nightly' || startsWith(github.head_ref, 'upgrade-latest/') || startsWith(github.head_ref, 'sync-dev-kit/') || github.head_ref == 'chore/sync-ctl-packages')) && 'pinned' || 'dev' }}
213
+ GITHUB_TOKEN: ${{ github.token }}
201
214
  run: |
202
215
  nix develop .#build --command bash -c '
203
216
  set -euo pipefail
@@ -208,6 +221,9 @@ jobs:
208
221
  # OLD checker against the new canonical). Cheap when already gone.
209
222
  find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
210
223
  bun install --frozen-lockfile
224
+ if [ "$SDK_LANE" = dev ] && [ -x .github/ci/sdk-dev.sh ]; then
225
+ bash .github/ci/sdk-dev.sh
226
+ fi
211
227
  bun run lint
212
228
  bun run typecheck
213
229
  # Known-flaky tests (.github/quarantine.json) leave the gating run
@@ -32,6 +32,9 @@ on:
32
32
 
33
33
  permissions:
34
34
  contents: read
35
+ # GitHub Packages needs a token even to read norsk's dev packages (the
36
+ # dev SDK lane below).
37
+ packages: read
35
38
 
36
39
  jobs:
37
40
  drift:
@@ -194,6 +197,16 @@ jobs:
194
197
  with:
195
198
  clean: true
196
199
  - name: Lint + typecheck + unit tests
200
+ env:
201
+ # The dev SDK lane, for a repo that opts in with .github/ci/sdk-dev.sh
202
+ # (norsk-relay): after the frozen install, the norsk SDKs are
203
+ # reinstalled from norsk's dev packages (every green push to norsk
204
+ # main, on GitHub Packages), so typecheck and unit run against norsk
205
+ # as it is now, not the nightly the tree pins -- a change that needs
206
+ # a norsk change merged this morning is green today. Not for a bot
207
+ # PR: a bump is asking about its pin. The committed pins are untouched.
208
+ SDK_LANE: ${{ (github.event_name == 'pull_request' && (github.head_ref == 'bump/nightly' || startsWith(github.head_ref, 'upgrade-latest/') || startsWith(github.head_ref, 'sync-dev-kit/') || github.head_ref == 'chore/sync-ctl-packages')) && 'pinned' || 'dev' }}
209
+ GITHUB_TOKEN: ${{ github.token }}
197
210
  run: |
198
211
  nix develop .#build --command bash -c '
199
212
  set -euo pipefail
@@ -204,6 +217,9 @@ jobs:
204
217
  # OLD checker against the new canonical). Cheap when already gone.
205
218
  find . -name node_modules -type d -prune -exec rm -rf {} + 2>/dev/null || true
206
219
  bun install --frozen-lockfile
220
+ if [ "$SDK_LANE" = dev ] && [ -x .github/ci/sdk-dev.sh ]; then
221
+ bash .github/ci/sdk-dev.sh
222
+ fi
207
223
  bun run lint
208
224
  bun run typecheck
209
225
  # Known-flaky tests (.github/quarantine.json) leave the gating run
@@ -247,6 +247,20 @@ spawnSync("docker", ["run", "--rm", "--user", "0:0", "-v", `${dirname(storeDir)}
247
247
  "--entrypoint", "sh", STUDIO_IMAGE, "-c", `rm -rf /base/${basename(storeDir)}`]);
248
248
  ```
249
249
 
250
+ ## Sample media comes from the shared asset cache
251
+
252
+ Source presets' media (`camera1`, `camera2`) is fetched once per cache into
253
+ `${NORSK_ASSET_CACHE:-$HOME/.cache/norsk/assets}/media-examples/data/`, not
254
+ once per store. `startCameraSource` hardlinks a preset's file from there into
255
+ the daemon's store before starting it, so start sources through the harness
256
+ rather than `POST /api/sources` directly. When `NORSK_ASSET_CACHE` is set,
257
+ daemons are also pointed at the cache itself (`NORSK_CTL_SAMPLE_MEDIA_DIR`), so
258
+ it must be a path the host daemon can bind-mount: the convention workflows set
259
+ it to `_norsk-assets` beside `$RUNNER_TEMP`: one cache per runner instance
260
+ (its `_work` dir), kept across runs.
261
+ Leave it unset in a hand-owned workflow on these runners rather than pointing
262
+ it under `$HOME`, which is the runner container's own.
263
+
250
264
  ## Reaching served media / HLS output
251
265
 
252
266
  Studio reports playback URLs (HLS multivariant, WHIP endpoints) with the host it
@@ -133,6 +133,9 @@ jobs:
133
133
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
134
134
  mkdir -p "$base"
135
135
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
136
+ # The shared asset cache (sample media), kept across runs: under the work
137
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
138
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
136
139
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
137
140
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
138
141
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -641,6 +644,9 @@ jobs:
641
644
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
642
645
  mkdir -p "$base"
643
646
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
647
+ # The shared asset cache (sample media), kept across runs: under the work
648
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
649
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
644
650
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
645
651
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
646
652
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -78,6 +78,9 @@ jobs:
78
78
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
79
79
  mkdir -p "$base"
80
80
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
81
+ # The shared asset cache (sample media), kept across runs: under the work
82
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
83
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
81
84
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
82
85
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
83
86
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -134,6 +137,9 @@ jobs:
134
137
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
135
138
  mkdir -p "$base"
136
139
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
140
+ # The shared asset cache (sample media), kept across runs: under the work
141
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
142
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
137
143
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
138
144
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
139
145
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -498,6 +504,9 @@ jobs:
498
504
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
499
505
  mkdir -p "$base"
500
506
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
507
+ # The shared asset cache (sample media), kept across runs: under the work
508
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
509
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
501
510
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
502
511
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
503
512
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -74,6 +74,9 @@ jobs:
74
74
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
75
75
  mkdir -p "$base"
76
76
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
77
+ # The shared asset cache (sample media), kept across runs: under the work
78
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
79
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
77
80
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
78
81
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
79
82
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -431,6 +434,9 @@ jobs:
431
434
  base="$RUNNER_TEMP/nctt-$GITHUB_RUN_ID-$GITHUB_RUN_ATTEMPT"
432
435
  mkdir -p "$base"
433
436
  echo "NORSK_CTL_TEST_TMP=$base" >> "$GITHUB_ENV"
437
+ # The shared asset cache (sample media), kept across runs: under the work
438
+ # dir like the base, so the HOST daemon sees the path a daemon bind-mounts.
439
+ echo "NORSK_ASSET_CACHE=${RUNNER_TEMP%/*}/_norsk-assets" >> "$GITHUB_ENV"
434
440
  # Yesterday's bases hold dockerd-created root dirs, so a non-root rm
435
441
  # EACCESes. They cannot wedge a checkout, but they do fill the disk.
436
442
  for old in $(find "$RUNNER_TEMP" -maxdepth 1 -name 'nctt-*' -mtime +0 -printf '%f\n' 2>/dev/null || true); do
@@ -117,10 +117,37 @@ const devKitPackageJson = JSON.parse(readFileSync(new URL("../package.json", imp
117
117
  devDependencies?: Record<string, string>;
118
118
  };
119
119
 
120
+ // CI's dev-SDK lane (.github/ci/sdk-dev.sh) repoints the client line at norsk's
121
+ // dev packages: the pin becomes an npm alias `npm:@id3as/<name>@<ver>-dev-<sha8>`.
122
+ const DEV_ALIAS = /^npm:@id3as\/([a-z-]+)@(.+)$/;
123
+
124
+ /** The media image built from the same commit as the dev-kit's norsk-sdk pin.
125
+ * A nightly pin names the Docker Hub tag outright. A dev alias has no Docker
126
+ * Hub image; norsk's publish-dev workflow pushes those builds to
127
+ * ghcr.io/id3as/norsk:dev-<sha8>, the sha8 the dev version carries, so a
128
+ * product scaffolded in the dev lane is still one commit through and through
129
+ * (CI run 40706712210, 2026-10-28: the alias pasted into the tag was not a ref). */
130
+ export function mediaImageFor(sdkSpec: string): string {
131
+ const alias = DEV_ALIAS.exec(sdkSpec);
132
+ if (!alias) return `norskvideo/norsk:${sdkSpec}`;
133
+ const sha = /-dev-([0-9a-f]{8})(?:\+|$)/.exec(alias[2])?.[1];
134
+ if (!sha) throw new Error(`dev alias ${sdkSpec} carries no -dev-<sha8>; no media image can be named for it`);
135
+ return `ghcr.io/id3as/norsk:dev-${sha}`;
136
+ }
137
+
138
+ /** The spec a generated product declares for a client-line package. A version
139
+ * is shared by the whole line; a dev alias names one package, so each gets
140
+ * its own (norsk-api aliased to @id3as/norsk-sdk would install the wrong one). */
141
+ export function clientLineSpec(sdkSpec: string, name: string): string {
142
+ const alias = DEV_ALIAS.exec(sdkSpec);
143
+ return alias ? `npm:@id3as/${name.replace(/^@norskvideo\//, "")}@${alias[2]}` : sdkSpec;
144
+ }
120
145
  // Derived, never a second copy of the tag: a hardcoded default silently missed
121
146
  // every nightly sdk-bump, which moves the package.json line and nothing else.
122
147
  // Media's npm packages and image are built from one commit, so they share a tag.
123
- const DEFAULT_MEDIA_IMAGE = `norskvideo/norsk:${devKitPin(devKitPackageJson, "@norskvideo/norsk-sdk")}`;
148
+ const DEFAULT_MEDIA_LIB = devKitPin(devKitPackageJson, "@norskvideo/norsk-sdk");
149
+ const DEFAULT_MEDIA_IMAGE = mediaImageFor(DEFAULT_MEDIA_LIB);
150
+
124
151
  // Studio's npm packages and image ship from different commits, so its image tag
125
152
  // cannot be derived; it only has to sit on the lib pin's version line.
126
153
  const DEFAULT_STUDIO_IMAGE = "norskvideo/norsk-studio:1.30.0-2026-09-24-f57973c6";
@@ -189,7 +216,9 @@ export function shapeContext(opts: CreateProductOptions): ShapeContext {
189
216
  mediaImage,
190
217
  studioImage,
191
218
  studioLib: opts.studioLib ?? (opts.studioImage ? bareTag(studioImage) : DEFAULT_STUDIO_LIB),
192
- mediaLib: bareTag(mediaImage),
219
+ // An explicit image names the lib's version (one commit); the default
220
+ // lib spec is kept as the dev-kit declares it, alias and all.
221
+ mediaLib: opts.mediaImage ? bareTag(mediaImage) : DEFAULT_MEDIA_LIB,
193
222
  },
194
223
  canon: loadCanon(),
195
224
  features: resolveFeatures(opts),
@@ -16,6 +16,7 @@
16
16
 
17
17
  import { pinnedBunVersion } from "../conventions/check-drift.ts";
18
18
  import {
19
+ clientLineSpec,
19
20
  type GeneratedFile,
20
21
  PRODUCT_ZOD,
21
22
  type ShapeContext,
@@ -402,7 +403,7 @@ function rootPackageJson(ctx: ShapeContext): string {
402
403
  "shell-quote": "^1.9.0",
403
404
  "fast-xml-parser": "^5.10.1",
404
405
  "fast-uri": "^3.1.4",
405
- "@norskvideo/norsk-api": mediaLib,
406
+ "@norskvideo/norsk-api": clientLineSpec(mediaLib, "@norskvideo/norsk-api"),
406
407
  "@norskvideo/norsk-sdk": mediaLib,
407
408
  "@norskvideo/norsk-studio": studioLib,
408
409
  ...optionalStudioPins(ctx),
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-dev-kit",
3
- "version": "0.2.114",
3
+ "version": "0.2.116",
4
4
  "type": "module",
5
5
  "repository": {
6
6
  "type": "git",
@@ -29,6 +29,7 @@
29
29
  "./package.json": "./package.json",
30
30
  "./testing/byte-snapshot": "./testing/byte-snapshot.ts",
31
31
  "./testing/invariants": "./testing/invariants.ts",
32
+ "./workflow/codec-level": "./workflow/codec-level.ts",
32
33
  "./workflow/ladder": "./workflow/ladder.ts"
33
34
  },
34
35
  "bin": {
@@ -44,10 +45,10 @@
44
45
  },
45
46
  "devDependencies": {
46
47
  "@norskvideo/ctl-oas-to-ts": "^0.1.0",
47
- "@norskvideo/norsk-sdk": "1.3.1-2026-10-22-aeac91a4",
48
- "@norskvideo/norsk-studio": "1.30.0-2026-10-23-8e050eb4",
49
- "@norskvideo/norsk-studio-builder": "1.30.0-2026-10-23-8e050eb4",
50
- "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-23-8e050eb4",
48
+ "@norskvideo/norsk-sdk": "1.3.1-2026-10-27-8e095a74",
49
+ "@norskvideo/norsk-studio": "1.30.0-2026-10-26-896721cc",
50
+ "@norskvideo/norsk-studio-builder": "1.30.0-2026-10-26-896721cc",
51
+ "@norskvideo/norsk-studio-built-ins": "1.30.0-2026-10-26-896721cc",
51
52
  "@playwright/test": "^1.59.0",
52
53
  "@testing-library/jest-dom": "^6.9.1",
53
54
  "@testing-library/react": "^16.3.2",
@@ -0,0 +1,44 @@
1
+ // The lowest codec level a rung fits, from the spec's frame-size and sample-rate
2
+ // limits, never below 3.1 (what every rung used before, and what players expect
3
+ // as a floor). x264 tolerates an understated level; x265 refuses to open
4
+ // (encoder_create_failed, measured on the 50 fps UHD ladder), so both count
5
+ // frame rate, not just resolution.
6
+ type H264Level = 3.1 | 4 | 4.1 | 5 | 5.1;
7
+ type HevcLevel = 3.1 | 4 | 4.1 | 5 | 5.1 | 5.2;
8
+ type Rung = { width: number; height: number; fps: number };
9
+
10
+ // H.264 Table A-1: max macroblocks per frame and per second. Only the levels
11
+ // every encoder Studio drives accepts (quadra and nvidia have no 3.2 or 4.2):
12
+ // a rung between two steps up.
13
+ const H264: [H264Level, number, number][] = [
14
+ [3.1, 3600, 108_000],
15
+ [4, 8192, 245_760],
16
+ [5, 22_080, 589_824],
17
+ [5.1, 36_864, 983_040],
18
+ ];
19
+
20
+ // HEVC Table A.8 (Main tier): max luma samples per picture and per second.
21
+ const HEVC: [HevcLevel, number, number][] = [
22
+ [3.1, 983_040, 33_177_600],
23
+ [4, 2_228_224, 66_846_720],
24
+ [4.1, 2_228_224, 133_693_440],
25
+ [5, 8_912_896, 267_386_880],
26
+ [5.1, 8_912_896, 534_773_760],
27
+ [5.2, 8_912_896, 1_069_547_520],
28
+ ];
29
+
30
+ function lowest<L extends number>(table: [L, number, number][], perFrame: number, perSecond: number): L {
31
+ const fit = table.find(([, frame, second]) => perFrame <= frame && perSecond <= second) ?? table[table.length - 1];
32
+ if (!fit) throw new Error("empty level table");
33
+ return fit[0];
34
+ }
35
+
36
+ export const h264Level = (r: Rung): H264Level => {
37
+ const macroblocks = Math.ceil(r.width / 16) * Math.ceil(r.height / 16);
38
+ return lowest(H264, macroblocks, macroblocks * r.fps);
39
+ };
40
+
41
+ export const hevcLevel = (r: Rung): HevcLevel => lowest(HEVC, r.width * r.height, r.width * r.height * r.fps);
42
+
43
+ export const codecLevel = (r: Rung & { codec?: "h264" | "hevc" }): H264Level | HevcLevel =>
44
+ r.codec === "hevc" ? hevcLevel(r) : h264Level(r);
@@ -1,21 +1,25 @@
1
- // The shared shape of an encode-ladder rung and a named preset, single-sourced
2
- // for every ctl product. Products previously each carried their own
3
- // near-identical copy of these types in `shared/src/workflow/ladder-presets.ts`
4
- // (commentary's set, playout's `flagship`/`uhd-hevc`), whose comments already
5
- // noted they "mirror" one another — this is the shared home they mirror.
1
+ // The shared shape of an encode-ladder rung and a named preset, plus the
2
+ // ladders more than one product ships, single-sourced for every ctl product.
3
+ // Products previously each carried their own copy of these in
4
+ // `shared/src/workflow/ladder-presets.ts` (commentary, playout) or
5
+ // `shared/src/ladders.ts` (recipes); the copies agreed value for value.
6
6
  //
7
- // What lives here is the SHAPE and the product-agnostic helpers. The catalogue
8
- // of presets and its key union stay per-product (they are genuinely different:
9
- // commentary ships `single`/`mobile`/`abr-internet`/`tv`/`vertical-mobile`,
10
- // playout ships `flagship`/`uhd-hevc`), as do product-specific rungs such as
11
- // commentary's fixed low-latency return-video rung. A product declares its
12
- // catalogue as `Record<ItsKey, LadderPreset>` over these types.
7
+ // What lives here: the SHAPE, the product-agnostic helpers, and the standard
8
+ // ladders (`STANDARD_LADDERS`: commentary's `single`/`mobile`/`abr-internet`/
9
+ // `tv`/`vertical-mobile` plus playout's `uhd-hevc`) with their named rungs
10
+ // (`STANDARD_RUNGS`), exactly as the products ship them today. A product picks
11
+ // the ladders it offers and adds its own, as `Record<ItsKey, LadderPreset>`
12
+ // over these types; ladders and rungs only one product uses stay with it
13
+ // (playout's `flagship`, commentary's fixed low-latency return-video rung).
14
+ // The codec level a rung needs is `codecLevel` in `./codec-level.ts`.
13
15
  //
14
- // Deliberately zero-dependency (plain types + a pure helper, no zod): the
15
- // per-product zod `RungSchema`s carry product-specific tuning (differing kbps
16
- // ceilings, playout's `codec` axis, distinct `.meta` ids) and the cycle-B
17
- // constraint that a schema module must not import a workflow module, so those
18
- // stay per-product and are a separate consolidation question.
16
+ // Deliberately zero-dependency (plain types, data and pure helpers, no zod).
17
+ // The zod `RungSchema` stays per product because the products accept
18
+ // different rungs: commentary and playout cap kbps at different ceilings, one
19
+ // requires `bitrateMode` where the other defaults it, playout has a `codec`
20
+ // axis where commentary has `x264Preset`, and each carries its own `.meta`
21
+ // ids. One shared schema would change what some product accepts. A schema
22
+ // module also must not import a workflow module (the cycle-B constraint).
19
23
 
20
24
  /**
21
25
  * One rung of an encode ladder: a single rendition's name, bitrate, resolution
@@ -49,3 +53,88 @@ export type LadderPreset = {
49
53
  export function isPortraitRung(rung: Pick<LadderRung, "width" | "height">): boolean {
50
54
  return rung.height > rung.width;
51
55
  }
56
+
57
+ /**
58
+ * The named rungs of the standard ladders. A rung that appears in two ladders
59
+ * (`abr_360`, `abr_480`) is the same rung in both.
60
+ */
61
+ export const STANDARD_RUNGS = {
62
+ default: { name: "default", kbps: 2000, width: 1280, height: 720, fps: 25, bitrateMode: "abr" },
63
+ abr_234: { name: "abr_234", kbps: 300, width: 416, height: 234, fps: 25, bitrateMode: "abr" },
64
+ abr_360: { name: "abr_360", kbps: 600, width: 640, height: 360, fps: 25, bitrateMode: "abr" },
65
+ abr_480: { name: "abr_480", kbps: 1200, width: 854, height: 480, fps: 25, bitrateMode: "abr" },
66
+ abr_720_2m: { name: "abr_720_2m", kbps: 2000, width: 1280, height: 720, fps: 25, bitrateMode: "abr" },
67
+ abr_720_4m: { name: "abr_720_4m", kbps: 4000, width: 1280, height: 720, fps: 25, bitrateMode: "abr" },
68
+ abr_720p: { name: "abr_720p", kbps: 2000, width: 1280, height: 720, fps: 25, bitrateMode: "abr" },
69
+ abr_1080p_4m: { name: "abr_1080p_4m", kbps: 4000, width: 1920, height: 1080, fps: 25, bitrateMode: "abr" },
70
+ abr_1080p_6m: { name: "abr_1080p_6m", kbps: 6000, width: 1920, height: 1080, fps: 25, bitrateMode: "abr" },
71
+ vertical_360: { name: "vertical_360", kbps: 600, width: 360, height: 640, fps: 30, bitrateMode: "abr" },
72
+ vertical_480: { name: "vertical_480", kbps: 1200, width: 480, height: 854, fps: 30, bitrateMode: "abr" },
73
+ vertical_720: { name: "vertical_720", kbps: 2500, width: 720, height: 1280, fps: 30, bitrateMode: "abr" },
74
+ hevc_3840x2160: {
75
+ name: "hevc_3840x2160",
76
+ kbps: 20000,
77
+ width: 3840,
78
+ height: 2160,
79
+ fps: 50,
80
+ bitrateMode: "abr",
81
+ codec: "hevc",
82
+ },
83
+ hevc_1920x1080: {
84
+ name: "hevc_1920x1080",
85
+ kbps: 8000,
86
+ width: 1920,
87
+ height: 1080,
88
+ fps: 50,
89
+ bitrateMode: "abr",
90
+ codec: "hevc",
91
+ },
92
+ hevc_1280x720: {
93
+ name: "hevc_1280x720",
94
+ kbps: 3000,
95
+ width: 1280,
96
+ height: 720,
97
+ fps: 50,
98
+ bitrateMode: "abr",
99
+ codec: "hevc",
100
+ },
101
+ } satisfies Record<string, LadderRung>;
102
+
103
+ export type StandardRungName = keyof typeof STANDARD_RUNGS;
104
+
105
+ export const STANDARD_LADDER_KEYS = ["single", "mobile", "abr-internet", "tv", "vertical-mobile", "uhd-hevc"] as const;
106
+ export type StandardLadderKey = (typeof STANDARD_LADDER_KEYS)[number];
107
+
108
+ const R = STANDARD_RUNGS;
109
+
110
+ /**
111
+ * The ladders more than one product offers, with the labels and rungs they
112
+ * ship today. A product spreads the ones it offers into its own catalogue.
113
+ */
114
+ export const STANDARD_LADDERS: Record<StandardLadderKey, LadderPreset> = {
115
+ single: {
116
+ label: "Single rung (720p25 @ 2000 kbps)",
117
+ rungs: [R.default],
118
+ },
119
+ mobile: {
120
+ label: "Mobile (3 rungs, 234p–480p, 300–1200 kbps)",
121
+ rungs: [R.abr_234, R.abr_360, R.abr_480],
122
+ },
123
+ "abr-internet": {
124
+ label: "ABR for internet (4 rungs, 360p–720p, 600–4000 kbps)",
125
+ rungs: [R.abr_360, R.abr_480, R.abr_720_2m, R.abr_720_4m],
126
+ },
127
+ tv: {
128
+ label: "TV (3 rungs, 720p–1080p, 2000–6000 kbps)",
129
+ rungs: [R.abr_720p, R.abr_1080p_4m, R.abr_1080p_6m],
130
+ },
131
+ // Portrait rungs for vertical delivery; assumes a portrait (or reframed) picture.
132
+ "vertical-mobile": {
133
+ label: "Vertical mobile (3 rungs, 640–1280 tall, 600–2500 kbps)",
134
+ rungs: [R.vertical_360, R.vertical_480, R.vertical_720],
135
+ },
136
+ "uhd-hevc": {
137
+ label: "UHD HEVC (3 rungs, 720p–2160p, 3–20 Mbps)",
138
+ rungs: [R.hevc_3840x2160, R.hevc_1920x1080, R.hevc_1280x720],
139
+ },
140
+ };