@norskvideo/ctl-dev-kit 0.2.115 → 0.2.117

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.
@@ -54,6 +54,12 @@ on:
54
54
 
55
55
  permissions:
56
56
  contents: read
57
+ # gate-checks calls checks.yml as a reusable workflow, and GitHub refuses to
58
+ # start a caller that grants less than its callee asks for (startup_failure,
59
+ # no jobs): every permission checks.yml / checks.sdk-app.yml declares must be
60
+ # here too. checks-callable.test.ts holds the two in step. packages: read is
61
+ # the dev SDK lane reading norsk's dev packages from GitHub Packages.
62
+ packages: read
57
63
 
58
64
  concurrency:
59
65
  group: ${{ github.workflow }}-${{ github.ref }}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@norskvideo/ctl-dev-kit",
3
- "version": "0.2.115",
3
+ "version": "0.2.117",
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": {
@@ -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
+ };