node-av 1.1.0 → 1.2.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 (134) hide show
  1. package/README.md +51 -38
  2. package/dist/api/bitstream-filter.d.ts +180 -123
  3. package/dist/api/bitstream-filter.js +180 -125
  4. package/dist/api/bitstream-filter.js.map +1 -1
  5. package/dist/api/decoder.d.ts +279 -132
  6. package/dist/api/decoder.js +285 -142
  7. package/dist/api/decoder.js.map +1 -1
  8. package/dist/api/encoder.d.ts +246 -162
  9. package/dist/api/encoder.js +272 -208
  10. package/dist/api/encoder.js.map +1 -1
  11. package/dist/api/filter-presets.d.ts +690 -94
  12. package/dist/api/filter-presets.js +686 -102
  13. package/dist/api/filter-presets.js.map +1 -1
  14. package/dist/api/filter.d.ts +249 -213
  15. package/dist/api/filter.js +252 -242
  16. package/dist/api/filter.js.map +1 -1
  17. package/dist/api/hardware.d.ts +224 -117
  18. package/dist/api/hardware.js +380 -214
  19. package/dist/api/hardware.js.map +1 -1
  20. package/dist/api/index.d.ts +3 -3
  21. package/dist/api/index.js +1 -1
  22. package/dist/api/index.js.map +1 -1
  23. package/dist/api/io-stream.d.ts +65 -61
  24. package/dist/api/io-stream.js +43 -46
  25. package/dist/api/io-stream.js.map +1 -1
  26. package/dist/api/media-input.d.ts +242 -140
  27. package/dist/api/media-input.js +205 -103
  28. package/dist/api/media-input.js.map +1 -1
  29. package/dist/api/media-output.d.ts +206 -128
  30. package/dist/api/media-output.js +210 -128
  31. package/dist/api/media-output.js.map +1 -1
  32. package/dist/api/pipeline.d.ts +168 -38
  33. package/dist/api/pipeline.js +238 -14
  34. package/dist/api/pipeline.js.map +1 -1
  35. package/dist/api/types.d.ts +21 -187
  36. package/dist/api/utils.d.ts +1 -2
  37. package/dist/api/utils.js +9 -0
  38. package/dist/api/utils.js.map +1 -1
  39. package/dist/lib/audio-fifo.d.ts +127 -170
  40. package/dist/lib/audio-fifo.js +130 -173
  41. package/dist/lib/audio-fifo.js.map +1 -1
  42. package/dist/lib/binding.js +5 -0
  43. package/dist/lib/binding.js.map +1 -1
  44. package/dist/lib/bitstream-filter-context.d.ts +139 -184
  45. package/dist/lib/bitstream-filter-context.js +139 -188
  46. package/dist/lib/bitstream-filter-context.js.map +1 -1
  47. package/dist/lib/bitstream-filter.d.ts +68 -54
  48. package/dist/lib/bitstream-filter.js +68 -54
  49. package/dist/lib/bitstream-filter.js.map +1 -1
  50. package/dist/lib/codec-context.d.ts +316 -380
  51. package/dist/lib/codec-context.js +316 -381
  52. package/dist/lib/codec-context.js.map +1 -1
  53. package/dist/lib/codec-parameters.d.ts +160 -170
  54. package/dist/lib/codec-parameters.js +162 -172
  55. package/dist/lib/codec-parameters.js.map +1 -1
  56. package/dist/lib/codec-parser.d.ts +91 -104
  57. package/dist/lib/codec-parser.js +92 -103
  58. package/dist/lib/codec-parser.js.map +1 -1
  59. package/dist/lib/codec.d.ts +264 -281
  60. package/dist/lib/codec.js +268 -285
  61. package/dist/lib/codec.js.map +1 -1
  62. package/dist/lib/dictionary.d.ts +149 -203
  63. package/dist/lib/dictionary.js +158 -212
  64. package/dist/lib/dictionary.js.map +1 -1
  65. package/dist/lib/error.d.ts +96 -130
  66. package/dist/lib/error.js +98 -128
  67. package/dist/lib/error.js.map +1 -1
  68. package/dist/lib/filter-context.d.ts +284 -218
  69. package/dist/lib/filter-context.js +290 -227
  70. package/dist/lib/filter-context.js.map +1 -1
  71. package/dist/lib/filter-graph.d.ts +251 -292
  72. package/dist/lib/filter-graph.js +253 -294
  73. package/dist/lib/filter-graph.js.map +1 -1
  74. package/dist/lib/filter-inout.d.ts +87 -95
  75. package/dist/lib/filter-inout.js +87 -95
  76. package/dist/lib/filter-inout.js.map +1 -1
  77. package/dist/lib/filter.d.ts +93 -111
  78. package/dist/lib/filter.js +93 -111
  79. package/dist/lib/filter.js.map +1 -1
  80. package/dist/lib/format-context.d.ts +320 -428
  81. package/dist/lib/format-context.js +313 -385
  82. package/dist/lib/format-context.js.map +1 -1
  83. package/dist/lib/frame.d.ts +262 -405
  84. package/dist/lib/frame.js +263 -408
  85. package/dist/lib/frame.js.map +1 -1
  86. package/dist/lib/hardware-device-context.d.ts +149 -203
  87. package/dist/lib/hardware-device-context.js +149 -203
  88. package/dist/lib/hardware-device-context.js.map +1 -1
  89. package/dist/lib/hardware-frames-context.d.ts +170 -180
  90. package/dist/lib/hardware-frames-context.js +171 -181
  91. package/dist/lib/hardware-frames-context.js.map +1 -1
  92. package/dist/lib/index.d.ts +2 -1
  93. package/dist/lib/index.js +2 -2
  94. package/dist/lib/index.js.map +1 -1
  95. package/dist/lib/input-format.d.ts +89 -117
  96. package/dist/lib/input-format.js +89 -117
  97. package/dist/lib/input-format.js.map +1 -1
  98. package/dist/lib/io-context.d.ts +209 -241
  99. package/dist/lib/io-context.js +220 -252
  100. package/dist/lib/io-context.js.map +1 -1
  101. package/dist/lib/log.d.ts +85 -119
  102. package/dist/lib/log.js +85 -122
  103. package/dist/lib/log.js.map +1 -1
  104. package/dist/lib/native-types.d.ts +117 -106
  105. package/dist/lib/native-types.js +0 -7
  106. package/dist/lib/native-types.js.map +1 -1
  107. package/dist/lib/option.d.ts +284 -241
  108. package/dist/lib/option.js +309 -249
  109. package/dist/lib/option.js.map +1 -1
  110. package/dist/lib/output-format.d.ts +77 -101
  111. package/dist/lib/output-format.js +77 -101
  112. package/dist/lib/output-format.js.map +1 -1
  113. package/dist/lib/packet.d.ts +172 -240
  114. package/dist/lib/packet.js +172 -241
  115. package/dist/lib/packet.js.map +1 -1
  116. package/dist/lib/rational.d.ts +0 -2
  117. package/dist/lib/rational.js +0 -2
  118. package/dist/lib/rational.js.map +1 -1
  119. package/dist/lib/software-resample-context.d.ts +241 -325
  120. package/dist/lib/software-resample-context.js +242 -326
  121. package/dist/lib/software-resample-context.js.map +1 -1
  122. package/dist/lib/software-scale-context.d.ts +129 -173
  123. package/dist/lib/software-scale-context.js +131 -175
  124. package/dist/lib/software-scale-context.js.map +1 -1
  125. package/dist/lib/stream.d.ts +87 -197
  126. package/dist/lib/stream.js +87 -197
  127. package/dist/lib/stream.js.map +1 -1
  128. package/dist/lib/utilities.d.ts +372 -181
  129. package/dist/lib/utilities.js +373 -182
  130. package/dist/lib/utilities.js.map +1 -1
  131. package/install/check.js +0 -1
  132. package/package.json +21 -12
  133. package/release_notes.md +43 -59
  134. package/CHANGELOG.md +0 -8
@@ -1,130 +1,93 @@
1
1
  import { bindings } from './binding.js';
2
2
  /**
3
- * Hardware device context for hardware acceleration.
3
+ * Hardware device context for GPU-accelerated processing.
4
4
  *
5
- * Manages hardware acceleration devices like CUDA, VAAPI, DXVA2, etc.
6
- * Provides device creation, configuration, and constraint querying.
7
- * Required for hardware-accelerated encoding, decoding, and filtering.
5
+ * Manages hardware acceleration devices for video encoding, decoding, and filtering.
6
+ * Provides access to GPU resources like CUDA, VAAPI, VideoToolbox, and other
7
+ * hardware acceleration APIs. Essential for high-performance video processing
8
+ * and reduced CPU usage.
8
9
  *
9
10
  * Direct mapping to FFmpeg's AVHWDeviceContext.
10
11
  *
11
12
  * @example
12
13
  * ```typescript
13
- * import { HardwareDeviceContext, HardwareFramesContext, FFmpegError } from 'node-av';
14
- * import { AV_HWDEVICE_TYPE_CUDA, AV_PIX_FMT_CUDA, AV_PIX_FMT_NV12 } from 'node-av/constants';
14
+ * import { HardwareDeviceContext, FFmpegError } from 'node-av';
15
+ * import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VIDEOTOOLBOX } from 'node-av/constants';
15
16
  *
16
- * // Create CUDA device context
17
+ * // Create hardware device
17
18
  * const device = new HardwareDeviceContext();
18
- * const ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, null);
19
- * FFmpegError.throwIfError(ret, 'create device');
19
+ * const ret = device.create(AV_HWDEVICE_TYPE_CUDA);
20
+ * FFmpegError.throwIfError(ret, 'create');
20
21
  *
21
- * // Get device constraints
22
- * const constraints = device.getHwframeConstraints();
23
- * console.log(`Max size: ${constraints.maxWidth}x${constraints.maxHeight}`);
24
- *
25
- * // Create frames context for this device
26
- * const frames = new HardwareFramesContext();
27
- * frames.alloc(device);
28
- * frames.format = AV_PIX_FMT_CUDA;
29
- * frames.swFormat = AV_PIX_FMT_NV12;
30
- * frames.width = 1920;
31
- * frames.height = 1080;
32
- * const initRet = frames.init();
33
- * FFmpegError.throwIfError(initRet, 'init frames');
34
- *
35
- * // Cleanup
36
- * frames.free();
37
- * device.free();
38
- * ```
39
- *
40
- * @example
41
- * ```typescript
42
- * import { HardwareDeviceContext } from 'node-av';
43
- * import { AV_HWDEVICE_TYPE_NONE } from 'node-av/constants';
44
- *
45
- * // List available hardware device types
22
+ * // List available hardware types
46
23
  * const types = HardwareDeviceContext.iterateTypes();
47
24
  * for (const type of types) {
48
25
  * const name = HardwareDeviceContext.getTypeName(type);
49
26
  * console.log(`Available: ${name}`);
50
27
  * }
51
28
  *
52
- * // Find specific device type
53
- * const vaapi = HardwareDeviceContext.findTypeByName('vaapi');
54
- * if (vaapi !== AV_HWDEVICE_TYPE_NONE) {
55
- * const device = new HardwareDeviceContext();
56
- * const ret = device.create(vaapi, '/dev/dri/renderD128', null);
57
- * FFmpegError.throwIfError(ret, 'create VAAPI device');
58
- * }
29
+ * // Use with decoder
30
+ * const codecContext = new CodecContext();
31
+ * codecContext.hwDeviceCtx = device;
32
+ *
33
+ * // Create derived context
34
+ * const derived = new HardwareDeviceContext();
35
+ * const ret2 = derived.createDerived(device, AV_HWDEVICE_TYPE_CUDA);
36
+ * FFmpegError.throwIfError(ret2, 'createDerived');
37
+ *
38
+ * // Cleanup
39
+ * device.free();
59
40
  * ```
60
41
  *
61
- * @see {@link HardwareFramesContext} For managing hardware frame pools
62
- * @see {@link CodecContext} For hardware-accelerated encoding/decoding
42
+ * @see [AVHWDeviceContext](https://ffmpeg.org/doxygen/trunk/structAVHWDeviceContext.html) - FFmpeg Doxygen
43
+ * @see {@link HardwareFramesContext} For hardware frame allocation
44
+ * @see {@link CodecContext} For hardware codec usage
63
45
  */
64
46
  export class HardwareDeviceContext {
65
47
  native;
66
- /**
67
- * Create a new hardware device context.
68
- *
69
- * The context is uninitialized - you must call alloc() or create() before use.
70
- * No FFmpeg resources are allocated until initialization.
71
- *
72
- * Direct wrapper around AVHWDeviceContext.
73
- *
74
- * @example
75
- * ```typescript
76
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
77
- * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
78
- *
79
- * const device = new HardwareDeviceContext();
80
- * const ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, null);
81
- * FFmpegError.throwIfError(ret, 'create device');
82
- * // Device is now ready for use
83
- * ```
84
- */
85
48
  constructor() {
86
49
  this.native = new bindings.HardwareDeviceContext();
87
50
  }
88
51
  /**
89
- * Get the string name of an AVHWDeviceType.
52
+ * Get human-readable name for hardware device type.
90
53
  *
91
- * Returns the human-readable name for a hardware device type.
54
+ * Converts a hardware device type enum to its string representation.
92
55
  *
93
- * Direct mapping to av_hwdevice_get_type_name()
56
+ * Direct mapping to av_hwdevice_get_type_name().
94
57
  *
95
- * @param type - Hardware device type (AVHWDeviceType)
96
- *
97
- * @returns Device type name or null if unknown
58
+ * @param type - Hardware device type
59
+ * @returns Type name string, or null if invalid
98
60
  *
99
61
  * @example
100
62
  * ```typescript
101
- * import { HardwareDeviceContext } from 'node-av';
102
63
  * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
103
64
  *
104
65
  * const name = HardwareDeviceContext.getTypeName(AV_HWDEVICE_TYPE_CUDA);
105
66
  * console.log(name); // "cuda"
106
67
  * ```
68
+ *
69
+ * @see {@link findTypeByName} For reverse lookup
107
70
  */
108
71
  static getTypeName(type) {
109
72
  return bindings.HardwareDeviceContext.getTypeName(type);
110
73
  }
111
74
  /**
112
- * Iterate over supported device types.
75
+ * List all supported hardware device types.
113
76
  *
114
- * Returns all hardware device types supported by this FFmpeg build.
77
+ * Returns an array of all hardware acceleration types available
78
+ * in the current FFmpeg build.
115
79
  *
116
- * Direct mapping to av_hwdevice_iterate_types()
80
+ * Direct mapping to av_hwdevice_iterate_types().
117
81
  *
118
- * @returns Array of supported AVHWDeviceType values
82
+ * @returns Array of available hardware device types
119
83
  *
120
84
  * @example
121
85
  * ```typescript
122
- * import { HardwareDeviceContext } from 'node-av';
123
- *
124
86
  * const types = HardwareDeviceContext.iterateTypes();
87
+ * console.log('Available hardware acceleration:');
125
88
  * for (const type of types) {
126
89
  * const name = HardwareDeviceContext.getTypeName(type);
127
- * console.log(`Supported: ${name}`);
90
+ * console.log(` - ${name}`);
128
91
  * }
129
92
  * ```
130
93
  */
@@ -132,26 +95,24 @@ export class HardwareDeviceContext {
132
95
  return bindings.HardwareDeviceContext.iterateTypes();
133
96
  }
134
97
  /**
135
- * Get the AVHWDeviceType corresponding to the name.
98
+ * Find hardware device type by name.
136
99
  *
137
- * Looks up a hardware device type by its string name.
100
+ * Converts a string name to the corresponding hardware device type enum.
138
101
  *
139
- * Direct mapping to av_hwdevice_find_type_by_name()
102
+ * Direct mapping to av_hwdevice_find_type_by_name().
140
103
  *
141
- * @param name - Device type name (e.g., "cuda", "vaapi", "dxva2")
142
- *
143
- * @returns AVHWDeviceType or AV_HWDEVICE_TYPE_NONE if not found
104
+ * @param name - Hardware type name (e.g., 'cuda', 'vaapi', 'videotoolbox')
105
+ * @returns Hardware device type enum, or AV_HWDEVICE_TYPE_NONE if not found
144
106
  *
145
107
  * @example
146
108
  * ```typescript
147
- * import { HardwareDeviceContext } from 'node-av';
148
- * import { AV_HWDEVICE_TYPE_NONE } from 'node-av/constants';
149
- *
150
109
  * const type = HardwareDeviceContext.findTypeByName('cuda');
151
110
  * if (type !== AV_HWDEVICE_TYPE_NONE) {
152
- * // CUDA is available
111
+ * console.log('CUDA is available');
153
112
  * }
154
113
  * ```
114
+ *
115
+ * @see {@link getTypeName} For type to name conversion
155
116
  */
156
117
  static findTypeByName(name) {
157
118
  return bindings.HardwareDeviceContext.findTypeByName(name);
@@ -159,244 +120,235 @@ export class HardwareDeviceContext {
159
120
  /**
160
121
  * Hardware device type.
161
122
  *
162
- * Direct mapping to AVHWDeviceContext->type
123
+ * The type of hardware acceleration in use.
163
124
  *
164
- * @readonly
125
+ * Direct mapping to AVHWDeviceContext->type.
165
126
  */
166
127
  get type() {
167
128
  return this.native.type;
168
129
  }
169
130
  /**
170
- * Hardware-specific data.
131
+ * Hardware context pointer.
171
132
  *
172
- * Direct mapping to AVHWDeviceContext->hwctx
133
+ * Opaque pointer to the underlying hardware-specific context.
134
+ * Type depends on the hardware device type.
173
135
  *
174
- * Returns opaque pointer as BigInt for advanced users.
175
- * @readonly
136
+ * Direct mapping to AVHWDeviceContext->hwctx.
176
137
  */
177
138
  get hwctx() {
178
139
  return this.native.hwctx;
179
140
  }
180
141
  /**
181
- * Allocate an AVHWDeviceContext for a given hardware type.
142
+ * Allocate hardware device context.
182
143
  *
183
- * Allocates the device context structure but doesn't open the device.
184
- * Must call init() after configuration to finalize.
144
+ * Allocates memory for the specified hardware device type.
145
+ * Must be followed by init() to initialize the device.
185
146
  *
186
- * Direct mapping to av_hwdevice_ctx_alloc()
147
+ * Direct mapping to av_hwdevice_ctx_alloc().
187
148
  *
188
- * @param type - Hardware device type
149
+ * @param type - Hardware device type to allocate
189
150
  *
190
- * @throws {Error} Memory allocation failure (ENOMEM)
151
+ * @throws {Error} If allocation fails (ENOMEM)
191
152
  *
192
153
  * @example
193
154
  * ```typescript
194
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
195
155
  * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
196
156
  *
197
157
  * const device = new HardwareDeviceContext();
198
158
  * device.alloc(AV_HWDEVICE_TYPE_CUDA);
199
- * // Configure device properties if needed
200
159
  * const ret = device.init();
201
- * FFmpegError.throwIfError(ret, 'init device');
160
+ * FFmpegError.throwIfError(ret, 'init');
202
161
  * ```
203
162
  *
204
- * @see {@link init} To finalize the device
205
- * @see {@link create} For one-step device creation
163
+ * @see {@link init} To initialize after allocation
164
+ * @see {@link create} For combined alloc and init
206
165
  */
207
166
  alloc(type) {
208
167
  this.native.alloc(type);
209
168
  }
210
169
  /**
211
- * Finalize the device context before use.
170
+ * Initialize allocated hardware device.
212
171
  *
213
- * Completes device initialization after alloc() and configuration.
214
- * Must be called before using the device context.
172
+ * Initializes a previously allocated hardware device context.
173
+ * Must be called after alloc() and before using the device.
215
174
  *
216
- * Direct mapping to av_hwdevice_ctx_init()
175
+ * Direct mapping to av_hwdevice_ctx_init().
217
176
  *
218
177
  * @returns 0 on success, negative AVERROR on error:
219
- * - 0: Success (device ready)
220
- * - AVERROR(EINVAL): Invalid parameters
221
- * - AVERROR(ENOMEM): Memory allocation failure
222
- * - <0: Device-specific errors
178
+ * - AVERROR_EINVAL: Invalid parameters
179
+ * - AVERROR_ENOMEM: Memory allocation failure
180
+ * - Device-specific errors
223
181
  *
224
182
  * @example
225
183
  * ```typescript
226
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
184
+ * import { FFmpegError } from 'node-av';
227
185
  *
186
+ * device.alloc(type);
228
187
  * const ret = device.init();
229
- * FFmpegError.throwIfError(ret, 'init device');
230
- * // Device is now ready for use
188
+ * FFmpegError.throwIfError(ret, 'init');
231
189
  * ```
232
190
  *
233
191
  * @see {@link alloc} Must be called first
192
+ * @see {@link create} For combined operation
234
193
  */
235
194
  init() {
236
195
  return this.native.init();
237
196
  }
238
197
  /**
239
- * Open a device of the specified type and create an AVHWDeviceContext.
198
+ * Create and initialize hardware device.
240
199
  *
241
- * One-step device creation that allocates, opens, and initializes the device.
242
- * This is the preferred method for creating hardware devices.
200
+ * Combined allocation and initialization of a hardware device.
201
+ * This is the preferred method for creating hardware contexts.
243
202
  *
244
- * Direct mapping to av_hwdevice_ctx_create()
203
+ * Direct mapping to av_hwdevice_ctx_create().
245
204
  *
246
205
  * @param type - Hardware device type
247
- * @param device - Device to open (e.g., "/dev/dri/renderD128" for VAAPI), or null for default
248
- * @param options - Device creation options, or null
249
- *
206
+ * @param device - Device name/path (null for default)
207
+ * @param options - Device-specific options
250
208
  * @returns 0 on success, negative AVERROR on error:
251
- * - 0: Success (device created and ready)
252
- * - AVERROR(EINVAL): Invalid parameters
253
- * - AVERROR(ENOMEM): Memory allocation failure
254
- * - AVERROR(ENOSYS): Device type not supported
255
- * - <0: Device-specific errors
209
+ * - AVERROR_EINVAL: Invalid type or parameters
210
+ * - AVERROR_ENOMEM: Memory allocation failure
211
+ * - AVERROR_ENOSYS: Type not supported
212
+ * - Device-specific errors
256
213
  *
257
214
  * @example
258
215
  * ```typescript
259
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
260
- * import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VAAPI } from 'node-av/constants';
261
- *
262
- * // Create CUDA device
263
- * const ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, null);
264
- * FFmpegError.throwIfError(ret, 'create CUDA device');
265
- *
266
- * // Create VAAPI device with specific device
267
- * const ret2 = device.create(
268
- * AV_HWDEVICE_TYPE_VAAPI,
269
- * '/dev/dri/renderD128',
270
- * null
271
- * );
272
- * FFmpegError.throwIfError(ret2, 'create VAAPI device');
216
+ * import { FFmpegError, Dictionary } from 'node-av';
217
+ * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
218
+ *
219
+ * // Create with default device
220
+ * const device = new HardwareDeviceContext();
221
+ * let ret = device.create(AV_HWDEVICE_TYPE_CUDA);
222
+ * FFmpegError.throwIfError(ret, 'create');
223
+ *
224
+ * // Create with specific device
225
+ * const device2 = new HardwareDeviceContext();
226
+ * ret = device2.create(AV_HWDEVICE_TYPE_VAAPI, '/dev/dri/renderD128');
227
+ * FFmpegError.throwIfError(ret, 'create');
228
+ *
229
+ * // Create with options
230
+ * const opts = Dictionary.fromObject({ 'device_idx': '1' });
231
+ * ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, opts);
232
+ * FFmpegError.throwIfError(ret, 'create');
273
233
  * ```
274
234
  *
275
- * @see {@link alloc} For manual device allocation
276
- * @see {@link createDerived} To derive from another device
235
+ * @see {@link createDerived} To create from existing device
277
236
  */
278
237
  create(type, device = null, options = null) {
279
238
  return this.native.create(type, device, options?.getNative() ?? null);
280
239
  }
281
240
  /**
282
- * Create a new device of the specified type from an existing device.
241
+ * Create derived hardware device.
283
242
  *
284
- * Creates a device that shares resources with the source device.
285
- * Useful for interop between different hardware APIs.
243
+ * Creates a new device context derived from an existing one.
244
+ * Used for interoperability between different hardware APIs.
286
245
  *
287
- * Direct mapping to av_hwdevice_ctx_create_derived()
246
+ * Direct mapping to av_hwdevice_ctx_create_derived().
288
247
  *
289
248
  * @param source - Source device context to derive from
290
249
  * @param type - Target hardware device type
291
- *
292
250
  * @returns 0 on success, negative AVERROR on error:
293
- * - 0: Success (derived device created)
294
- * - AVERROR(ENOSYS): Derivation not supported
295
- * - AVERROR(EINVAL): Invalid parameters
296
- * - <0: Other errors
251
+ * - AVERROR_EINVAL: Invalid parameters
252
+ * - AVERROR_ENOSYS: Derivation not supported
253
+ * - AVERROR_ENOMEM: Memory allocation failure
297
254
  *
298
255
  * @example
299
256
  * ```typescript
300
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
301
- * import { AV_HWDEVICE_TYPE_VAAPI, AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
257
+ * import { FFmpegError } from 'node-av';
258
+ * import { AV_HWDEVICE_TYPE_CUDA, AV_HWDEVICE_TYPE_VULKAN } from 'node-av/constants';
302
259
  *
303
- * // Create CUDA device from VAAPI device
304
- * const vaapi = new HardwareDeviceContext();
305
- * const vaapiRet = vaapi.create(AV_HWDEVICE_TYPE_VAAPI, null, null);
306
- * FFmpegError.throwIfError(vaapiRet, 'create VAAPI');
260
+ * // Create CUDA device from Vulkan
261
+ * const vulkan = new HardwareDeviceContext();
262
+ * vulkan.create(AV_HWDEVICE_TYPE_VULKAN);
307
263
  *
308
264
  * const cuda = new HardwareDeviceContext();
309
- * const ret = cuda.createDerived(vaapi, AV_HWDEVICE_TYPE_CUDA);
310
- * FFmpegError.throwIfError(ret, 'derive CUDA from VAAPI');
265
+ * const ret = cuda.createDerived(vulkan, AV_HWDEVICE_TYPE_CUDA);
266
+ * FFmpegError.throwIfError(ret, 'createDerived');
311
267
  * ```
312
268
  *
313
- * @see {@link create} For standalone device creation
269
+ * @see {@link create} For creating independent device
314
270
  */
315
271
  createDerived(source, type) {
316
272
  return this.native.createDerived(source.native, type);
317
273
  }
318
274
  /**
319
- * Free the device context.
275
+ * Free hardware device context.
320
276
  *
321
- * Unreferences the AVBufferRef and releases all device resources.
277
+ * Releases all resources associated with the hardware device.
278
+ * The context becomes invalid after calling this.
322
279
  *
323
- * Direct mapping to av_buffer_unref()
280
+ * Direct mapping to av_buffer_unref() on device context.
324
281
  *
325
282
  * @example
326
283
  * ```typescript
327
- * import { HardwareDeviceContext } from 'node-av';
328
- *
329
284
  * device.free();
330
- * // device is now invalid and should not be used
285
+ * // Device is now invalid
331
286
  * ```
287
+ *
288
+ * @see {@link Symbol.dispose} For automatic cleanup
332
289
  */
333
290
  free() {
334
291
  this.native.free();
335
292
  }
336
293
  /**
337
- * Allocate a HW-specific configuration structure.
294
+ * Allocate hardware configuration.
338
295
  *
339
- * Allocates a configuration structure for querying device constraints.
296
+ * Allocates a hardware-specific configuration structure.
297
+ * Used for codec configuration with hardware acceleration.
340
298
  *
341
- * Direct mapping to av_hwdevice_hwconfig_alloc()
299
+ * Direct mapping to av_hwdevice_hwconfig_alloc().
342
300
  *
343
- * @returns Opaque pointer as BigInt or null
301
+ * @returns Configuration pointer, or null on failure
344
302
  *
345
303
  * @example
346
304
  * ```typescript
347
- * import { HardwareDeviceContext } from 'node-av';
348
- *
349
305
  * const hwconfig = device.hwconfigAlloc();
350
306
  * if (hwconfig) {
351
- * // Use with getHwframeConstraints
352
- * const constraints = device.getHwframeConstraints(hwconfig);
307
+ * // Use with codec context
308
+ * codecContext.hwConfig = hwconfig;
353
309
  * }
354
310
  * ```
355
311
  *
356
- * @see {@link getHwframeConstraints} To use the configuration
312
+ * @see {@link getHwframeConstraints} To get constraints
357
313
  */
358
314
  hwconfigAlloc() {
359
315
  return this.native.hwconfigAlloc();
360
316
  }
361
317
  /**
362
- * Get the constraints on HW frames given a device and parameters.
318
+ * Get hardware frame constraints.
363
319
  *
364
- * Queries the device for supported formats, sizes, and other constraints.
365
- * Essential for configuring hardware frames contexts.
320
+ * Returns the constraints on frames that can be allocated
321
+ * with this hardware device.
366
322
  *
367
- * Direct mapping to av_hwdevice_get_hwframe_constraints()
323
+ * Direct mapping to av_hwdevice_get_hwframe_constraints().
368
324
  *
369
- * @param hwconfig - Hardware configuration from hwconfigAlloc(), or undefined
370
- *
371
- * @returns Constraints object or null:
372
- * - Object: Device constraints
373
- * - null: No constraints available
325
+ * @param hwconfig - Optional hardware configuration
326
+ * @returns Frame constraints, or null if not available
374
327
  *
375
328
  * @example
376
329
  * ```typescript
377
- * import { HardwareDeviceContext } from 'node-av';
378
- *
379
330
  * const constraints = device.getHwframeConstraints();
380
331
  * if (constraints) {
381
- * console.log(`Size range: ${constraints.minWidth}x${constraints.minHeight} to ${constraints.maxWidth}x${constraints.maxHeight}`);
382
- *
332
+ * console.log(`Min size: ${constraints.minWidth}x${constraints.minHeight}`);
333
+ * console.log(`Max size: ${constraints.maxWidth}x${constraints.maxHeight}`);
383
334
  * if (constraints.validSwFormats) {
384
- * console.log('Valid software formats:', constraints.validSwFormats);
335
+ * console.log('Software formats:', constraints.validSwFormats);
336
+ * }
337
+ * if (constraints.validHwFormats) {
338
+ * console.log('Hardware formats:', constraints.validHwFormats);
385
339
  * }
386
340
  * }
387
341
  * ```
388
- *
389
- * @see {@link hwconfigAlloc} To create configuration
390
- * @see {@link HardwareFramesContext} To use with frame pools
391
342
  */
392
343
  getHwframeConstraints(hwconfig) {
393
344
  return this.native.getHwframeConstraints(hwconfig);
394
345
  }
395
346
  /**
396
- * Get the native FFmpeg AVHWDeviceContext pointer.
347
+ * Get the underlying native HardwareDeviceContext object.
348
+ *
349
+ * @returns The native HardwareDeviceContext binding object
397
350
  *
398
- * @internal For use by other wrapper classes
399
- * @returns The underlying native hardware device context object
351
+ * @internal
400
352
  */
401
353
  getNative() {
402
354
  return this.native;
@@ -409,18 +361,12 @@ export class HardwareDeviceContext {
409
361
  *
410
362
  * @example
411
363
  * ```typescript
412
- * import { HardwareDeviceContext, FFmpegError } from 'node-av';
413
- * import { AV_HWDEVICE_TYPE_CUDA } from 'node-av/constants';
414
- *
415
364
  * {
416
365
  * using device = new HardwareDeviceContext();
417
- * const ret = device.create(AV_HWDEVICE_TYPE_CUDA, null, null);
418
- * FFmpegError.throwIfError(ret, 'create device');
419
- * // ... use device
366
+ * device.create(AV_HWDEVICE_TYPE_CUDA);
367
+ * // Use device...
420
368
  * } // Automatically freed when leaving scope
421
369
  * ```
422
- *
423
- * @see {@link free} For manual cleanup
424
370
  */
425
371
  [Symbol.dispose]() {
426
372
  this.native[Symbol.dispose]();
@@ -1 +1 @@
1
- {"version":3,"file":"hardware-device-context.js","sourceRoot":"","sources":["../../src/lib/hardware-device-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA6DG;AACH,MAAM,OAAO,qBAAqB;IACxB,MAAM,CAA8B;IAE5C;;;;;;;;;;;;;;;;;;OAkBG;IACH;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,WAAW,CAAC,IAAoB;QACrC,OAAO,QAAQ,CAAC,qBAAqB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,YAAY;QACjB,OAAO,QAAQ,CAAC,qBAAqB,CAAC,YAAY,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,MAAM,CAAC,cAAc,CAAC,IAAY;QAChC,OAAO,QAAQ,CAAC,qBAAqB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,KAAK,CAAC,IAAoB;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,IAAoB,EAAE,SAAwB,IAAI,EAAE,UAA6B,IAAI;QAC1F,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAiCG;IACH,aAAa,CAAC,MAA6B,EAAE,IAAoB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;OAqBG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,qBAAqB,CAAC,QAAiB;QAQrC,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,CAAC;CACF"}
1
+ {"version":3,"file":"hardware-device-context.js","sourceRoot":"","sources":["../../src/lib/hardware-device-context.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAMxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GA2CG;AACH,MAAM,OAAO,qBAAqB;IACxB,MAAM,CAA8B;IAE5C;QACE,IAAI,CAAC,MAAM,GAAG,IAAI,QAAQ,CAAC,qBAAqB,EAAE,CAAC;IACrD,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,WAAW,CAAC,IAAoB;QACrC,OAAO,QAAQ,CAAC,qBAAqB,CAAC,WAAW,CAAC,IAAI,CAAC,CAAC;IAC1D,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,YAAY;QACjB,OAAO,QAAQ,CAAC,qBAAqB,CAAC,YAAY,EAAE,CAAC;IACvD,CAAC;IAED;;;;;;;;;;;;;;;;;;;OAmBG;IACH,MAAM,CAAC,cAAc,CAAC,IAAY;QAChC,OAAO,QAAQ,CAAC,qBAAqB,CAAC,cAAc,CAAC,IAAI,CAAC,CAAC;IAC7D,CAAC;IAED;;;;;;OAMG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,KAAK,CAAC,IAAoB;QACxB,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;IAC1B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,IAAI;QACF,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IAC5B,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OAuCG;IACH,MAAM,CAAC,IAAoB,EAAE,SAAwB,IAAI,EAAE,UAA6B,IAAI;QAC1F,OAAO,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,IAAI,EAAE,MAAM,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,IAAI,CAAC,CAAC;IACxE,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,aAAa,CAAC,MAA6B,EAAE,IAAoB;QAC/D,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,CAAC,MAAM,CAAC,MAAM,EAAE,IAAI,CAAC,CAAC;IACxD,CAAC;IAED;;;;;;;;;;;;;;;OAeG;IACH,IAAI;QACF,IAAI,CAAC,MAAM,CAAC,IAAI,EAAE,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,aAAa;QACX,OAAO,IAAI,CAAC,MAAM,CAAC,aAAa,EAAE,CAAC;IACrC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;OAyBG;IACH,qBAAqB,CAAC,QAAiB;QAQrC,OAAO,IAAI,CAAC,MAAM,CAAC,qBAAqB,CAAC,QAAQ,CAAC,CAAC;IACrD,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;IAED;;;;;;;;;;;;;;OAcG;IACH,CAAC,MAAM,CAAC,OAAO,CAAC;QACd,IAAI,CAAC,MAAM,CAAC,MAAM,CAAC,OAAO,CAAC,EAAE,CAAC;IAChC,CAAC;CACF"}