@appium/media-proxy 0.0.1 → 1.1.0

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.
Files changed (123) hide show
  1. package/CHANGELOG.md +33 -0
  2. package/LICENSE +201 -0
  3. package/README.md +183 -2
  4. package/THIRD_PARTY_NOTICES.md +29 -0
  5. package/binding.gyp +90 -0
  6. package/lib/src/background.d.ts +5 -0
  7. package/lib/src/background.d.ts.map +1 -0
  8. package/lib/src/background.js +16 -0
  9. package/lib/src/background.js.map +1 -0
  10. package/lib/src/capabilities.d.ts +9 -0
  11. package/lib/src/capabilities.d.ts.map +1 -0
  12. package/lib/src/capabilities.js +11 -0
  13. package/lib/src/capabilities.js.map +1 -0
  14. package/lib/src/errors.d.ts +26 -0
  15. package/lib/src/errors.d.ts.map +1 -0
  16. package/lib/src/errors.js +40 -0
  17. package/lib/src/errors.js.map +1 -0
  18. package/lib/src/framing/apst.d.ts +43 -0
  19. package/lib/src/framing/apst.d.ts.map +1 -0
  20. package/lib/src/framing/apst.js +126 -0
  21. package/lib/src/framing/apst.js.map +1 -0
  22. package/lib/src/framing/mjpeg-http.d.ts +30 -0
  23. package/lib/src/framing/mjpeg-http.d.ts.map +1 -0
  24. package/lib/src/framing/mjpeg-http.js +148 -0
  25. package/lib/src/framing/mjpeg-http.js.map +1 -0
  26. package/lib/src/framing/mjpeg-multipart.d.ts +11 -0
  27. package/lib/src/framing/mjpeg-multipart.d.ts.map +1 -0
  28. package/lib/src/framing/mjpeg-multipart.js +26 -0
  29. package/lib/src/framing/mjpeg-multipart.js.map +1 -0
  30. package/lib/src/index.d.ts +10 -0
  31. package/lib/src/index.d.ts.map +1 -0
  32. package/lib/src/index.js +7 -0
  33. package/lib/src/index.js.map +1 -0
  34. package/lib/src/native.d.ts +12 -0
  35. package/lib/src/native.d.ts.map +1 -0
  36. package/lib/src/native.js +36 -0
  37. package/lib/src/native.js.map +1 -0
  38. package/lib/src/pkg-root.d.ts +6 -0
  39. package/lib/src/pkg-root.d.ts.map +1 -0
  40. package/lib/src/pkg-root.js +12 -0
  41. package/lib/src/pkg-root.js.map +1 -0
  42. package/lib/src/queue.d.ts +34 -0
  43. package/lib/src/queue.d.ts.map +1 -0
  44. package/lib/src/queue.js +123 -0
  45. package/lib/src/queue.js.map +1 -0
  46. package/lib/src/transcoder.d.ts +81 -0
  47. package/lib/src/transcoder.d.ts.map +1 -0
  48. package/lib/src/transcoder.js +422 -0
  49. package/lib/src/transcoder.js.map +1 -0
  50. package/lib/src/types.d.ts +147 -0
  51. package/lib/src/types.d.ts.map +1 -0
  52. package/lib/src/types.js +2 -0
  53. package/lib/src/types.js.map +1 -0
  54. package/package.json +53 -4
  55. package/prebuilds/darwin-arm64/@appium+media-proxy.node +0 -0
  56. package/prebuilds/darwin-arm64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  57. package/prebuilds/darwin-arm64/ffmpeg-build-info.txt +3 -0
  58. package/prebuilds/darwin-arm64/libavcodec-appium.62.dylib +0 -0
  59. package/prebuilds/darwin-arm64/libavutil-appium.60.dylib +0 -0
  60. package/prebuilds/darwin-arm64/libswscale-appium.9.dylib +0 -0
  61. package/prebuilds/darwin-x64/@appium+media-proxy.node +0 -0
  62. package/prebuilds/darwin-x64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  63. package/prebuilds/darwin-x64/ffmpeg-build-info.txt +3 -0
  64. package/prebuilds/darwin-x64/libavcodec-appium.62.dylib +0 -0
  65. package/prebuilds/darwin-x64/libavutil-appium.60.dylib +0 -0
  66. package/prebuilds/darwin-x64/libswscale-appium.9.dylib +0 -0
  67. package/prebuilds/linux-arm64/@appium+media-proxy.node +0 -0
  68. package/prebuilds/linux-arm64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  69. package/prebuilds/linux-arm64/ffmpeg-build-info.txt +3 -0
  70. package/prebuilds/linux-arm64/libavcodec-appium.so.62 +0 -0
  71. package/prebuilds/linux-arm64/libavutil-appium.so.60 +0 -0
  72. package/prebuilds/linux-arm64/libswscale-appium.so.9 +0 -0
  73. package/prebuilds/linux-x64/@appium+media-proxy.node +0 -0
  74. package/prebuilds/linux-x64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  75. package/prebuilds/linux-x64/ffmpeg-build-info.txt +3 -0
  76. package/prebuilds/linux-x64/libavcodec-appium.so.62 +0 -0
  77. package/prebuilds/linux-x64/libavutil-appium.so.60 +0 -0
  78. package/prebuilds/linux-x64/libswscale-appium.so.9 +0 -0
  79. package/prebuilds/win32-arm64/@appium+media-proxy.node +0 -0
  80. package/prebuilds/win32-arm64/avcodec-appium-62.dll +0 -0
  81. package/prebuilds/win32-arm64/avutil-appium-60.dll +0 -0
  82. package/prebuilds/win32-arm64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  83. package/prebuilds/win32-arm64/ffmpeg-build-info.txt +3 -0
  84. package/prebuilds/win32-arm64/swscale-appium-9.dll +0 -0
  85. package/prebuilds/win32-x64/@appium+media-proxy.node +0 -0
  86. package/prebuilds/win32-x64/avcodec-appium-62.dll +0 -0
  87. package/prebuilds/win32-x64/avutil-appium-60.dll +0 -0
  88. package/prebuilds/win32-x64/ffmpeg-LICENSE-LGPL-2.1.txt +502 -0
  89. package/prebuilds/win32-x64/ffmpeg-build-info.txt +3 -0
  90. package/prebuilds/win32-x64/swscale-appium-9.dll +0 -0
  91. package/scripts/install.mjs +29 -0
  92. package/src/background.ts +15 -0
  93. package/src/capabilities.ts +12 -0
  94. package/src/errors.ts +45 -0
  95. package/src/framing/apst.ts +158 -0
  96. package/src/framing/mjpeg-http.ts +186 -0
  97. package/src/framing/mjpeg-multipart.ts +38 -0
  98. package/src/index.ts +43 -0
  99. package/src/native/addon.cc +402 -0
  100. package/src/native/audio_pipeline.cc +426 -0
  101. package/src/native/audio_pipeline.h +63 -0
  102. package/src/native/ffmpeg_util.h +37 -0
  103. package/src/native/h264_encoder.cc +133 -0
  104. package/src/native/h264_encoder.h +48 -0
  105. package/src/native/mediafoundation_encoder.cc +442 -0
  106. package/src/native/mediafoundation_encoder.h +14 -0
  107. package/src/native/napi_util.h +20 -0
  108. package/src/native/openh264_encoder.cc +285 -0
  109. package/src/native/openh264_encoder.h +14 -0
  110. package/src/native/pipeline.cc +555 -0
  111. package/src/native/pipeline.h +108 -0
  112. package/src/native/vendor/openh264/LICENSE +23 -0
  113. package/src/native/vendor/openh264/codec_api.h +592 -0
  114. package/src/native/vendor/openh264/codec_app_def.h +820 -0
  115. package/src/native/vendor/openh264/codec_def.h +216 -0
  116. package/src/native/vendor/openh264/codec_ver.h +15 -0
  117. package/src/native/videotoolbox_encoder.cc +314 -0
  118. package/src/native/videotoolbox_encoder.h +13 -0
  119. package/src/native.ts +51 -0
  120. package/src/pkg-root.ts +14 -0
  121. package/src/queue.ts +133 -0
  122. package/src/transcoder.ts +480 -0
  123. package/src/types.ts +158 -0
package/src/queue.ts ADDED
@@ -0,0 +1,133 @@
1
+ export const MAX_BUFFERED_UNITS = 60;
2
+
3
+ /**
4
+ * Single-consumer FIFO between the native callback and `units()`. Bounded: on overflow the backlog
5
+ * is cleared (except units `keepOnOverflow` accepts) and, while `dropsDuringResync` says so, further units are discarded until `endsResync`
6
+ * sees a self-decodable one — dropping an arbitrary P-frame would corrupt every later one.
7
+ */
8
+ export class UnitQueue<T> {
9
+ private readonly buffer: T[] = [];
10
+ private waiter: {resolve: (r: IteratorResult<T>) => void; reject: (e: unknown) => void} | undefined;
11
+ private ended = false;
12
+ private draining = false;
13
+ private error: unknown;
14
+ private resyncing = false;
15
+
16
+ constructor(
17
+ private readonly opts: {
18
+ dropsDuringResync: (unit: T) => boolean;
19
+ endsResync: (unit: T) => boolean;
20
+ onOverflow?: () => void;
21
+ keepOnOverflow?: (unit: T) => boolean;
22
+ capacity?: number;
23
+ },
24
+ ) {}
25
+
26
+ push(unit: T): void {
27
+ if (this.ended) {
28
+ return;
29
+ }
30
+ if (this.resyncing) {
31
+ if (this.opts.dropsDuringResync(unit)) {
32
+ return;
33
+ }
34
+ if (this.opts.endsResync(unit)) {
35
+ this.resyncing = false;
36
+ }
37
+ }
38
+ if (this.waiter) {
39
+ const {resolve} = this.waiter;
40
+ this.waiter = undefined;
41
+ resolve({value: unit, done: false});
42
+ return;
43
+ }
44
+ this.buffer.push(unit);
45
+ const capacity = this.opts.capacity ?? MAX_BUFFERED_UNITS;
46
+ if (this.buffer.length > capacity) {
47
+ const {keepOnOverflow} = this.opts;
48
+ const kept = keepOnOverflow ? this.buffer.filter(keepOnOverflow) : [];
49
+ const dropped = kept.length < this.buffer.length;
50
+ // Kept units alone may still exceed the capacity: drop their oldest.
51
+ this.buffer.splice(0, this.buffer.length, ...kept.slice(-capacity));
52
+ if (dropped) {
53
+ this.resyncing = true;
54
+ this.opts.onOverflow?.();
55
+ }
56
+ }
57
+ }
58
+
59
+ fail(err: unknown): void {
60
+ if (this.ended) {
61
+ return;
62
+ }
63
+ this.ended = true;
64
+ this.draining = false;
65
+ this.error = err;
66
+ this.buffer.length = 0;
67
+ if (this.waiter) {
68
+ const {reject} = this.waiter;
69
+ this.waiter = undefined;
70
+ reject(err);
71
+ }
72
+ }
73
+
74
+ /**
75
+ * Ends the queue. With `drain`, already buffered units are still delivered before `next()`
76
+ * resolves `done`; otherwise they are discarded (also if called again while draining).
77
+ */
78
+ end(opts: {drain?: boolean} = {}): void {
79
+ if (this.ended) {
80
+ // A non-draining end cancels a drain already in progress.
81
+ if (!opts.drain && this.draining) {
82
+ this.draining = false;
83
+ this.buffer.length = 0;
84
+ }
85
+ return;
86
+ }
87
+ this.ended = true;
88
+ if (opts.drain && this.buffer.length > 0) {
89
+ this.draining = true;
90
+ return;
91
+ }
92
+ this.buffer.length = 0;
93
+ if (this.waiter) {
94
+ const {resolve} = this.waiter;
95
+ this.waiter = undefined;
96
+ resolve({value: undefined, done: true});
97
+ }
98
+ }
99
+
100
+ /** Resolves `done` if `signal` aborts or the queue has ended; never serves stale units after that. */
101
+ next(signal: AbortSignal): Promise<IteratorResult<T>> {
102
+ if (signal.aborted) {
103
+ return Promise.resolve({value: undefined, done: true});
104
+ }
105
+ if (this.ended && !this.draining) {
106
+ return this.error ? Promise.reject(this.error) : Promise.resolve({value: undefined, done: true});
107
+ }
108
+ const buffered = this.buffer.shift();
109
+ if (this.draining && this.buffer.length === 0) {
110
+ this.draining = false;
111
+ }
112
+ if (buffered !== undefined) {
113
+ return Promise.resolve({value: buffered, done: false});
114
+ }
115
+ return new Promise((resolve, reject) => {
116
+ const onAbort = () => {
117
+ this.waiter = undefined;
118
+ resolve({value: undefined, done: true});
119
+ };
120
+ signal.addEventListener('abort', onAbort, {once: true});
121
+ this.waiter = {
122
+ resolve: (result) => {
123
+ signal.removeEventListener('abort', onAbort);
124
+ resolve(result);
125
+ },
126
+ reject: (err) => {
127
+ signal.removeEventListener('abort', onAbort);
128
+ reject(err);
129
+ },
130
+ };
131
+ });
132
+ }
133
+ }
@@ -0,0 +1,480 @@
1
+ import {releaseQuietly} from './background.js';
2
+ import {MediaProxyOptionError, wrapNativeError} from './errors.js';
3
+ import {loadNative} from './native.js';
4
+ import {MAX_BUFFERED_UNITS, UnitQueue} from './queue.js';
5
+ import type {
6
+ AudioAccessUnit,
7
+ H264Options,
8
+ JpegFrame,
9
+ MjpegOptions,
10
+ NalAccessUnit,
11
+ NativeConfig,
12
+ NativeModule,
13
+ NativeTranscoderHandle,
14
+ NativeUnit,
15
+ Rotation,
16
+ TranscoderOptions,
17
+ VideoAccessUnit,
18
+ } from './types.js';
19
+
20
+ export const DEFAULT_FPS = 60;
21
+ export const DEFAULT_BITRATE = 4_000_000;
22
+ export const DEFAULT_QUALITY = 80;
23
+ export const DEFAULT_SCALE = 100;
24
+ /** AAC-LC output rate per channel (coresim's setting). */
25
+ const AUDIO_BITRATE_PER_CHANNEL = 64_000;
26
+ /** AAC-ELD, 48 kHz stereo, 480-sample frames: the device's stream as it really is (remotexpc `aac-eld.ts`). */
27
+ export const DEFAULT_AUDIO_SPECIFIC_CONFIG = Buffer.from([0xf8, 0xe6, 0x50, 0x00]);
28
+ /**
29
+ * RTP video clock of the device's screen stream. Measured on an iPad (iPadOS 27.0.1): 400 ticks per frame at
30
+ * 60 fps, not the 90 kHz RFC 7798 suggests, so a wrong value slows the media timeline and starves the fps limiter.
31
+ * `videoClockRate` overrides it for a source that is known to differ.
32
+ */
33
+ const DEFAULT_VIDEO_CLOCK_RATE = 24_000;
34
+ const AUDIO_CLOCK_RATE = 48_000;
35
+
36
+ const MAX_BITRATE = 2 ** 31 - 1;
37
+ /** About 5 s of 10 ms audio units. */
38
+ const MAX_BUFFERED_AUDIO_UNITS = 500;
39
+
40
+ /** Validates `opts` and fills in the defaults, with the same rules and error type as coresim. */
41
+ export function resolveOptions(opts: TranscoderOptions): NativeConfig {
42
+ if (opts?.codec !== 'h264' && opts?.codec !== 'mjpeg') {
43
+ throw new MediaProxyOptionError(
44
+ `codec must be 'h264' or 'mjpeg', got ${String((opts as {codec?: unknown})?.codec)}`,
45
+ );
46
+ }
47
+ const fps = opts.fps ?? DEFAULT_FPS;
48
+ if (!Number.isFinite(fps) || fps < 1) {
49
+ throw new RangeError(`fps must be a finite number >= 1, got ${fps}`);
50
+ }
51
+ let bitrate = DEFAULT_BITRATE;
52
+ let quality = DEFAULT_QUALITY;
53
+ let scale = DEFAULT_SCALE;
54
+ let audio = false;
55
+ let audioSpecificConfig: Buffer = DEFAULT_AUDIO_SPECIFIC_CONFIG;
56
+ if (opts.codec === 'h264') {
57
+ audio = opts.audio ?? false;
58
+ if (opts.audioSpecificConfig !== undefined) {
59
+ if (!Buffer.isBuffer(opts.audioSpecificConfig) || opts.audioSpecificConfig.length === 0) {
60
+ throw new RangeError('audioSpecificConfig must be a non-empty Buffer');
61
+ }
62
+ audioSpecificConfig = opts.audioSpecificConfig;
63
+ }
64
+ bitrate = opts.bitrate ?? DEFAULT_BITRATE;
65
+ if (!Number.isFinite(bitrate) || bitrate <= 0 || bitrate > MAX_BITRATE) {
66
+ throw new RangeError(`bitrate must be a positive number no greater than ${MAX_BITRATE}, got ${bitrate}`);
67
+ }
68
+ } else {
69
+ quality = opts.quality ?? DEFAULT_QUALITY;
70
+ if (!Number.isFinite(quality) || quality < 0 || quality > 100) {
71
+ throw new RangeError(`quality must be a number between 0 and 100, got ${quality}`);
72
+ }
73
+ scale = opts.scale ?? DEFAULT_SCALE;
74
+ if (!Number.isFinite(scale) || scale <= 0 || scale > 100) {
75
+ throw new RangeError(`scale must be a number greater than 0 and no greater than 100, got ${scale}`);
76
+ }
77
+ }
78
+ const {crop} = opts;
79
+ if (crop !== undefined) {
80
+ for (const [side, value] of [
81
+ ['width', crop.width],
82
+ ['height', crop.height],
83
+ ] as const) {
84
+ if (!Number.isInteger(value) || value <= 0 || value % 2 !== 0) {
85
+ throw new RangeError(`crop.${side} must be a positive even integer, got ${value}`);
86
+ }
87
+ }
88
+ }
89
+ const rotation = opts.rotation ?? 0;
90
+ assertRotation(rotation);
91
+ return {
92
+ outputCodec: opts.codec,
93
+ fps,
94
+ bitrate,
95
+ quality,
96
+ scale,
97
+ audio,
98
+ audioSpecificConfig,
99
+ audioBitratePerChannel: AUDIO_BITRATE_PER_CHANNEL,
100
+ cropWidth: crop?.width ?? 0,
101
+ cropHeight: crop?.height ?? 0,
102
+ rotation,
103
+ };
104
+ }
105
+
106
+ function assertRotation(degrees: unknown): asserts degrees is Rotation {
107
+ if (degrees !== 0 && degrees !== 90 && degrees !== 180 && degrees !== 270) {
108
+ throw new RangeError(`rotation must be 0, 90, 180 or 270, got ${String(degrees)}`);
109
+ }
110
+ }
111
+
112
+ /** Converts 32-bit RTP timestamps to microseconds since the first unit, unwrapping the counter. */
113
+ export class TimestampConverter {
114
+ private base: number | undefined;
115
+ private last = 0;
116
+ private ticks = 0;
117
+
118
+ constructor(private readonly clockRate: number = DEFAULT_VIDEO_CLOCK_RATE) {
119
+ if (!Number.isFinite(clockRate) || clockRate <= 0) {
120
+ throw new RangeError(`videoClockRate must be a positive finite number, got ${clockRate}`);
121
+ }
122
+ }
123
+
124
+ toMicros(timestamp: number): number {
125
+ if (this.base === undefined) {
126
+ this.base = timestamp;
127
+ } else {
128
+ // Signed 32-bit delta handles wrap-around and small reorderings.
129
+ this.ticks += (timestamp - this.last) | 0;
130
+ }
131
+ this.last = timestamp;
132
+ return Math.max(0, Math.round((this.ticks * 1_000_000) / this.clockRate));
133
+ }
134
+ }
135
+
136
+ type OutputUnit = VideoAccessUnit | JpegFrame;
137
+
138
+ /** A running transcoder. Single `units()` consumer at a time. */
139
+ export class Transcoder<U extends OutputUnit = OutputUnit> {
140
+ private readonly handle: NativeTranscoderHandle;
141
+ private readonly queue: UnitQueue<U>;
142
+ private readonly clock: TimestampConverter;
143
+ private readonly audioClock = new TimestampConverter(AUDIO_CLOCK_RATE);
144
+ private readonly isVideo: boolean;
145
+ private readonly hasAudio: boolean;
146
+ private readonly stopController = new AbortController();
147
+ private sequence = 0;
148
+ private audioSequence = 0;
149
+ // Arrival time of the very first unit (either track) and each track's offset from it, in µs.
150
+ private originMs: number | undefined;
151
+ private videoOffset: number | undefined;
152
+ private audioOffset: number | undefined;
153
+ private closePromise: Promise<void> | undefined;
154
+ private consuming = false;
155
+
156
+ /** @internal use {@link createTranscoder}; `backend` is injectable for tests. */
157
+ constructor(opts: TranscoderOptions, backend?: NativeModule) {
158
+ // Validate before touching the addon, so bad options are reported even where it's unavailable.
159
+ const config = resolveOptions(opts);
160
+ this.clock = new TimestampConverter(opts.videoClockRate ?? DEFAULT_VIDEO_CLOCK_RATE);
161
+ const native = backend ?? loadNative();
162
+ this.isVideo = config.outputCodec === 'h264';
163
+ this.hasAudio = config.audio;
164
+ // Audio units are never dropped and never end a resync: only video frames depend on each other.
165
+ this.queue = new UnitQueue<U>(
166
+ this.isVideo
167
+ ? {
168
+ dropsDuringResync: (u) => (u as VideoAccessUnit).track === 'video' && !(u as VideoAccessUnit).isKeyFrame,
169
+ endsResync: (u) => (u as VideoAccessUnit).track === 'video' && (u as VideoAccessUnit).isKeyFrame,
170
+ keepOnOverflow: (u) => (u as VideoAccessUnit).track === 'audio',
171
+ onOverflow: () => this.handle?.requestKeyFrame(),
172
+ capacity: MAX_BUFFERED_UNITS + (this.hasAudio ? MAX_BUFFERED_AUDIO_UNITS : 0),
173
+ }
174
+ : {dropsDuringResync: () => false, endsResync: () => true},
175
+ );
176
+ try {
177
+ this.handle = native.createTranscoder(
178
+ config,
179
+ (unit) => this.onUnit(unit),
180
+ // oxlint-disable-next-line promise/prefer-await-to-callbacks -- native error callback, not a promise API
181
+ (err) => this.queue.fail(wrapNativeError(err)),
182
+ );
183
+ } catch (err) {
184
+ throw wrapNativeError(err);
185
+ }
186
+ }
187
+
188
+ /** Feeds one access unit (non-blocking; the native side queues and may drop to the next keyframe). */
189
+ push(au: NalAccessUnit): void {
190
+ if (this.closePromise) {
191
+ return;
192
+ }
193
+ try {
194
+ const micros = this.clock.toMicros(au.timestamp);
195
+ this.videoOffset ??= this.offsetFrom(au.receivedAt);
196
+ this.handle.push(au.nals, micros + this.videoOffset, au.isKeyFrame);
197
+ } catch (err) {
198
+ throw wrapNativeError(err);
199
+ }
200
+ }
201
+
202
+ /** Feeds one AAC-ELD access unit; needs `audio: true`. Timestamps are aligned with the video by arrival time. */
203
+ pushAudio(au: AudioAccessUnit): void {
204
+ if (!this.hasAudio) {
205
+ throw new MediaProxyOptionError("pushAudio() requires the 'audio' option");
206
+ }
207
+ if (this.closePromise) {
208
+ return;
209
+ }
210
+ try {
211
+ const micros = this.audioClock.toMicros(au.timestamp);
212
+ this.audioOffset ??= this.offsetFrom(au.receivedAt);
213
+ this.handle.pushAudio(au.data, micros + this.audioOffset);
214
+ } catch (err) {
215
+ throw wrapNativeError(err);
216
+ }
217
+ }
218
+
219
+ /**
220
+ * Makes the next H.264 output a keyframe, e.g. for a consumer that joined a running stream. Takes
221
+ * effect with the next input unit, so it needs the source to keep sending. Requests made before that unit
222
+ * are one request (the native side only sets a flag), but each later one forces another keyframe, so
223
+ * callers that serve several consumers should coalesce them. A no-op for MJPEG (every frame is standalone)
224
+ * and after {@link end}/{@link close}.
225
+ */
226
+ requestKeyFrame(): void {
227
+ if (!this.isVideo || this.closePromise) {
228
+ return;
229
+ }
230
+ try {
231
+ this.handle.requestKeyFrame();
232
+ } catch (err) {
233
+ throw wrapNativeError(err);
234
+ }
235
+ }
236
+
237
+ /**
238
+ * Changes the clockwise rotation that makes the picture upright, while streaming. The next frame is turned
239
+ * and, since the output changes shape, starts with a keyframe: a quarter turn swaps the output's width and
240
+ * height, so a new SPS (H.264) or a differently sized JPEG tells the consumer. A no-op after
241
+ * {@link end}/{@link close}.
242
+ */
243
+ setRotation(degrees: Rotation): void {
244
+ assertRotation(degrees);
245
+ if (this.closePromise) {
246
+ return;
247
+ }
248
+ try {
249
+ this.handle.setRotation(degrees);
250
+ } catch (err) {
251
+ throw wrapNativeError(err);
252
+ }
253
+ }
254
+
255
+ /** Microseconds between the stream's first arrival (either track) and `receivedAt`. */
256
+ private offsetFrom(receivedAt: number | undefined): number {
257
+ const now = receivedAt ?? performance.now();
258
+ this.originMs ??= now;
259
+ return Math.max(0, Math.round((now - this.originMs) * 1000));
260
+ }
261
+
262
+ async *units(signal?: AbortSignal): AsyncGenerator<U> {
263
+ if (this.consuming) {
264
+ throw new MediaProxyOptionError('units() supports only one active consumer at a time');
265
+ }
266
+ this.consuming = true;
267
+ const combined = signal ? AbortSignal.any([signal, this.stopController.signal]) : this.stopController.signal;
268
+ try {
269
+ for (;;) {
270
+ const result = await this.queue.next(combined);
271
+ if (result.done) {
272
+ return;
273
+ }
274
+ yield result.value;
275
+ }
276
+ } finally {
277
+ this.consuming = false;
278
+ }
279
+ }
280
+
281
+ /**
282
+ * Finishes the stream: flushes the pipeline, so `units()` yields everything already produced and
283
+ * then completes. Idempotent; a no-op after {@link close}.
284
+ */
285
+ end(): Promise<void> {
286
+ this.closePromise ??= (async () => {
287
+ try {
288
+ await this.handle.close();
289
+ } catch (err) {
290
+ const wrapped = wrapNativeError(err);
291
+ this.queue.fail(wrapped);
292
+ throw wrapped;
293
+ }
294
+ this.queue.end({drain: true});
295
+ })();
296
+ return this.closePromise;
297
+ }
298
+
299
+ /** Stops immediately, discarding unconsumed units. Idempotent; pending `units()` iterators complete. */
300
+ close(): Promise<void> {
301
+ // Stop consumers first, even if end() already started: native close() may still flush units
302
+ // nobody wants, and a draining queue must be discarded.
303
+ this.stopController.abort();
304
+ this.queue.end();
305
+ this.closePromise ??= this.handle.close();
306
+ return this.closePromise;
307
+ }
308
+
309
+ private onUnit(unit: NativeUnit): void {
310
+ const out: OutputUnit = this.isVideo
311
+ ? {
312
+ track: unit.audio ? 'audio' : 'video',
313
+ data: unit.data,
314
+ isKeyFrame: unit.isKeyFrame,
315
+ sequence: unit.audio ? this.audioSequence++ : this.sequence++,
316
+ timestampMicros: unit.timestampMicros,
317
+ }
318
+ : {data: unit.data, sequence: this.sequence++, timestampMicros: unit.timestampMicros};
319
+ this.queue.push(out as U);
320
+ }
321
+ }
322
+
323
+ /** Creates a transcoder; throws `MediaProxyUnavailableError` if the addon can't be loaded here. */
324
+ export function createTranscoder(opts: H264Options): Transcoder<VideoAccessUnit>;
325
+ export function createTranscoder(opts: MjpegOptions): Transcoder<JpegFrame>;
326
+ export function createTranscoder(opts: TranscoderOptions): Transcoder<VideoAccessUnit> | Transcoder<JpegFrame>;
327
+ export function createTranscoder(opts: TranscoderOptions): Transcoder<VideoAccessUnit> | Transcoder<JpegFrame> {
328
+ return new Transcoder<VideoAccessUnit | JpegFrame>(opts) as Transcoder<VideoAccessUnit> | Transcoder<JpegFrame>;
329
+ }
330
+
331
+ /**
332
+ * Pipes `source` (e.g. remotexpc's `ScreenStreamCapture.accessUnits()`) through a transcoder. When
333
+ * the source finishes, everything already produced is still yielded; if it fails, that error is
334
+ * thrown after the remaining units. Stopping early (`break`, `signal`) closes the transcoder and asks
335
+ * the source to stop via `return()`; a source blocked on an idle read can only finish once it
336
+ * yields or honours its own abort signal, which is not awaited.
337
+ */
338
+ export function transcode(
339
+ source: AsyncIterable<NalAccessUnit>,
340
+ opts: H264Options,
341
+ signal?: AbortSignal,
342
+ audioSource?: AsyncIterable<AudioAccessUnit>,
343
+ ): AsyncGenerator<VideoAccessUnit>;
344
+ export function transcode(
345
+ source: AsyncIterable<NalAccessUnit>,
346
+ opts: MjpegOptions,
347
+ signal?: AbortSignal,
348
+ ): AsyncGenerator<JpegFrame>;
349
+ export async function* transcode(
350
+ source: AsyncIterable<NalAccessUnit>,
351
+ opts: TranscoderOptions,
352
+ signal?: AbortSignal,
353
+ audioSource?: AsyncIterable<AudioAccessUnit>,
354
+ ): AsyncGenerator<OutputUnit> {
355
+ if (audioSource && !(opts.codec === 'h264' && opts.audio)) {
356
+ throw new MediaProxyOptionError("audioSource requires codec 'h264' with audio: true");
357
+ }
358
+ yield* pipeThrough(createTranscoder(opts), source, signal, audioSource);
359
+ }
360
+
361
+ /** @internal `transcode()` with an already-created transcoder (injectable backend for tests). */
362
+ export async function* pipeThrough(
363
+ transcoder: Transcoder<VideoAccessUnit> | Transcoder<JpegFrame>,
364
+ source: AsyncIterable<NalAccessUnit>,
365
+ signal?: AbortSignal,
366
+ audioSource?: AsyncIterable<AudioAccessUnit>,
367
+ ): AsyncGenerator<OutputUnit> {
368
+ let iterator: AsyncIterator<NalAccessUnit>;
369
+ let audioIterator: AsyncIterator<AudioAccessUnit> | undefined;
370
+ try {
371
+ iterator = source[Symbol.asyncIterator]();
372
+ audioIterator = audioSource?.[Symbol.asyncIterator]();
373
+ } catch (err) {
374
+ await transcoder.close().catch(() => {});
375
+ throw err;
376
+ }
377
+ let stopped = false;
378
+ let exhausted = false;
379
+ let returned = false;
380
+ let failed = false;
381
+ let pumpError: unknown;
382
+ // Don't await: an idle source may not settle until its next item.
383
+ const releaseSource = () => {
384
+ if (!exhausted && !returned) {
385
+ returned = true;
386
+ releaseQuietly(iterator);
387
+ }
388
+ };
389
+ let audioDone = false;
390
+ const releaseAudio = () => {
391
+ if (audioIterator && !audioDone) {
392
+ audioDone = true;
393
+ releaseQuietly(audioIterator);
394
+ }
395
+ };
396
+ const fail = (err: unknown) => {
397
+ if (!failed) {
398
+ failed = true;
399
+ pumpError = err;
400
+ }
401
+ };
402
+ // Audio follows the video: it ends with it, and its failure ends the stream like a video failure.
403
+ // Never awaited: an idle audio read may not settle until its next item, and it can't fail the stream afterwards.
404
+ void (async () => {
405
+ if (!audioIterator) {
406
+ return;
407
+ }
408
+ try {
409
+ for (;;) {
410
+ const result = await audioIterator.next();
411
+ if (result.done) {
412
+ audioDone = true;
413
+ return;
414
+ }
415
+ if (stopped || audioDone) {
416
+ return;
417
+ }
418
+ transcoder.pushAudio(result.value);
419
+ }
420
+ } catch (err) {
421
+ audioDone = true;
422
+ fail(err);
423
+ releaseSource();
424
+ if (!stopped) {
425
+ await transcoder.end().catch(() => {});
426
+ }
427
+ }
428
+ })();
429
+ const pump = (async () => {
430
+ try {
431
+ for (;;) {
432
+ let result: IteratorResult<NalAccessUnit>;
433
+ try {
434
+ result = await iterator.next();
435
+ } catch (err) {
436
+ exhausted = true;
437
+ throw err;
438
+ }
439
+ if (result.done) {
440
+ exhausted = true;
441
+ break;
442
+ }
443
+ if (stopped) {
444
+ break;
445
+ }
446
+ transcoder.push(result.value);
447
+ }
448
+ } catch (err) {
449
+ fail(err);
450
+ }
451
+ releaseSource();
452
+ releaseAudio();
453
+ if (!stopped) {
454
+ // A close failure reaches the consumer through the queue; keep the pump from rejecting.
455
+ await transcoder.end().catch(() => {});
456
+ }
457
+ })();
458
+ try {
459
+ yield* transcoder.units(signal);
460
+ } finally {
461
+ stopped = true;
462
+ try {
463
+ await transcoder.close();
464
+ } finally {
465
+ releaseSource();
466
+ releaseAudio();
467
+ }
468
+ }
469
+ if (signal?.aborted) {
470
+ return;
471
+ }
472
+ // A failure is reported without waiting for the pump: an idle video read may never settle.
473
+ if (failed) {
474
+ throw pumpError;
475
+ }
476
+ await pump;
477
+ if (failed) {
478
+ throw pumpError;
479
+ }
480
+ }