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,11 +1,12 @@
1
1
  import type { AVFormatFlag } from '../constants/constants.js';
2
2
  import type { NativeInputFormat, NativeIOContext, NativeWrapper } from './native-types.js';
3
3
  /**
4
- * Input format (demuxer) descriptor.
4
+ * Input format descriptor for demuxing media files.
5
5
  *
6
- * Describes a supported input container format for demuxing.
7
- * Provides format information like name, extensions, and capabilities.
8
- * These are read-only format descriptors managed by FFmpeg.
6
+ * Represents a demuxer that can read and parse specific media container formats.
7
+ * Each format handles specific file types (e.g., MP4, MKV, AVI) and knows how to
8
+ * extract streams and packets from them. Used to identify and open media files
9
+ * for reading.
9
10
  *
10
11
  * Direct mapping to FFmpeg's AVInputFormat.
11
12
  *
@@ -13,204 +14,175 @@ import type { NativeInputFormat, NativeIOContext, NativeWrapper } from './native
13
14
  * ```typescript
14
15
  * import { InputFormat, FormatContext, FFmpegError } from 'node-av';
15
16
  *
16
- * // Find a specific input format
17
+ * // Find format by name
17
18
  * const mp4Format = InputFormat.findInputFormat('mp4');
18
19
  * if (mp4Format) {
19
- * console.log(`Format: ${mp4Format.longName}`);
20
+ * console.log(`Format: ${mp4Format.name}`);
21
+ * console.log(`Description: ${mp4Format.longName}`);
20
22
  * console.log(`Extensions: ${mp4Format.extensions}`);
21
23
  * }
22
24
  *
23
- * // Use with FormatContext
24
- * const ctx = new FormatContext();
25
- * ctx.allocContext();
25
+ * // Probe format from file data
26
+ * const fileData = Buffer.from([...]); // First few KB of file
27
+ * const detectedFormat = InputFormat.probe(fileData, 'video.mp4');
28
+ * if (detectedFormat) {
29
+ * console.log(`Detected: ${detectedFormat.name}`);
30
+ * }
26
31
  *
27
- * // Force a specific input format
28
- * const movFormat = InputFormat.findInputFormat('mov');
29
- * const ret = await ctx.openInput('video.dat', movFormat, null);
32
+ * // Use with format context
33
+ * const formatContext = new FormatContext();
34
+ * formatContext.inputFormat = mp4Format;
35
+ * const ret = await formatContext.openInput('video.mp4');
30
36
  * FFmpegError.throwIfError(ret, 'openInput');
31
37
  * ```
32
38
  *
33
- * @see {@link FormatContext} For using input formats
34
- * @see {@link OutputFormat} For output formats
39
+ * @see [AVInputFormat](https://ffmpeg.org/doxygen/trunk/structAVInputFormat.html) - FFmpeg Doxygen
40
+ * @see {@link FormatContext} For using formats to open files
41
+ * @see {@link OutputFormat} For muxing formats
35
42
  */
36
43
  export declare class InputFormat implements NativeWrapper<NativeInputFormat> {
37
44
  private native;
38
45
  /**
39
- * Constructor is internal - use static factory methods.
40
- *
41
- * InputFormats are obtained via static methods, not created directly.
42
- * FFmpeg manages these format descriptors internally.
43
- *
46
+ * @param native - The native input format instance
44
47
  * @internal
45
- *
46
- * @param native - Native AVInputFormat to wrap
47
- *
48
- * @example
49
- * ```typescript
50
- * import { InputFormat } from 'node-av';
51
- *
52
- * // Don't use constructor directly
53
- * // const format = new InputFormat(); // Wrong
54
- *
55
- * // Use static factory methods instead
56
- * const format = InputFormat.findInputFormat('mp4'); // Correct
57
- * ```
58
48
  */
59
49
  constructor(native: NativeInputFormat);
60
50
  /**
61
- * Find a registered input format with matching name.
51
+ * Find input format by short name.
62
52
  *
63
- * Searches FFmpeg's registered demuxers by short name.
64
- * Useful for forcing a specific format when auto-detection fails.
53
+ * Searches for a demuxer by its short name identifier.
65
54
  *
66
- * Direct mapping to av_find_input_format()
55
+ * Direct mapping to av_find_input_format().
67
56
  *
68
- * @param shortName - Short name of the format (e.g., 'mp4', 'mov', 'avi')
69
- *
70
- * @returns InputFormat if found, null otherwise
57
+ * @param shortName - Format short name (e.g., 'mp4', 'mkv', 'avi')
58
+ * @returns Input format if found, null otherwise
71
59
  *
72
60
  * @example
73
61
  * ```typescript
74
- * import { InputFormat, FormatContext, FFmpegError } from 'node-av';
75
- *
76
- * const format = InputFormat.findInputFormat('mp4');
77
- * if (format) {
78
- * console.log(`Found: ${format.longName}`);
79
- * }
80
- *
81
- * // Force specific format when opening
82
- * const movFormat = InputFormat.findInputFormat('mov');
83
- * if (movFormat) {
84
- * const ctx = new FormatContext();
85
- * ctx.allocContext();
86
- * const ret = await ctx.openInput('video.dat', movFormat, null);
87
- * FFmpegError.throwIfError(ret, 'openInput');
62
+ * // Find specific formats
63
+ * const mp4 = InputFormat.findInputFormat('mp4');
64
+ * const mkv = InputFormat.findInputFormat('matroska');
65
+ * const avi = InputFormat.findInputFormat('avi');
66
+ *
67
+ * // Check if format is available
68
+ * if (!mp4) {
69
+ * console.error('MP4 format not available');
88
70
  * }
89
71
  * ```
72
+ *
73
+ * @see {@link probe} To auto-detect format
90
74
  */
91
75
  static findInputFormat(shortName: string): InputFormat | null;
92
76
  /**
93
- * Probe input format from buffer data.
77
+ * Probe format from buffer data.
94
78
  *
95
- * Attempts to detect the input format based on buffer contents.
96
- * This is a synchronous operation that analyzes buffer data to identify the format.
79
+ * Analyzes buffer content to determine the media format.
80
+ * Optionally uses filename for additional format hints.
97
81
  *
98
- * Direct mapping to av_probe_input_format3()
82
+ * Direct mapping to av_probe_input_format2().
99
83
  *
100
- * @param buffer - Buffer containing media data to probe
101
- * @param filename - Optional filename hint to aid detection
102
- *
103
- * @returns InputFormat if detected, null otherwise
84
+ * @param buffer - Buffer containing file header/start
85
+ * @param filename - Optional filename for format hints
86
+ * @returns Detected format, or null if not recognized
104
87
  *
105
88
  * @example
106
89
  * ```typescript
107
- * import { InputFormat } from 'node-av';
108
90
  * import { readFileSync } from 'fs';
109
91
  *
110
- * // Read first few KB of a media file
111
- * const buffer = readFileSync('video.mp4', { length: 4096 });
112
- * const format = InputFormat.probe(buffer, 'video.mp4');
92
+ * // Read first 4KB for probing
93
+ * const data = readFileSync('video.mp4').subarray(0, 4096);
94
+ * const format = InputFormat.probe(data, 'video.mp4');
113
95
  *
114
96
  * if (format) {
115
- * console.log(`Detected format: ${format.longName}`);
97
+ * console.log(`Detected format: ${format.name}`);
98
+ * } else {
99
+ * console.error('Unknown format');
116
100
  * }
117
101
  * ```
102
+ *
103
+ * @see {@link probeBuffer} For IO context probing
104
+ * @see {@link findInputFormat} To get format by name
118
105
  */
119
106
  static probe(buffer: Buffer, filename?: string): InputFormat | null;
120
107
  /**
121
- * Probe input format from IOContext buffer.
122
- *
123
- * Attempts to detect the input format by reading from an IOContext.
124
- * This is an asynchronous operation that reads data from the IOContext to identify the format.
125
- * The IOContext position may be changed during probing.
108
+ * Probe format from IO context.
126
109
  *
127
- * Direct mapping to av_probe_input_buffer2()
110
+ * Reads data from an IO context to determine format.
111
+ * Useful for custom IO scenarios and network streams.
128
112
  *
129
- * @param ioContext - IOContext to read data from for probing
130
- * @param maxProbeSize - Maximum bytes to read for probing (0 for default)
113
+ * Direct mapping to av_probe_input_buffer2().
131
114
  *
132
- * @returns Promise resolving to InputFormat if detected, null otherwise
115
+ * @param ioContext - IO context to read from
116
+ * @param ioContext.getNative - Method to get native IO context
117
+ * @param maxProbeSize - Maximum bytes to read for probing
118
+ * @returns Detected format, or null if not recognized
133
119
  *
134
120
  * @example
135
121
  * ```typescript
136
- * import { InputFormat, IOContext } from 'node-av';
122
+ * import { IOContext } from 'node-av';
137
123
  *
138
- * // Open an IOContext
139
- * const io = new IOContext();
140
- * await io.open2('video.mp4', AVIO_FLAG_READ);
141
- *
142
- * // Probe the format
143
- * const format = await InputFormat.probeBuffer(io);
124
+ * // Create custom IO context
125
+ * const ioContext = new IOContext();
126
+ * // ... configure IO context ...
144
127
  *
128
+ * // Probe format
129
+ * const format = await InputFormat.probeBuffer(ioContext, 32768);
145
130
  * if (format) {
146
- * console.log(`Detected format: ${format.longName}`);
131
+ * console.log(`Stream format: ${format.name}`);
147
132
  * }
148
- *
149
- * await io.closep();
150
133
  * ```
134
+ *
135
+ * @see {@link probe} For buffer probing
151
136
  */
152
137
  static probeBuffer(ioContext: {
153
138
  getNative(): NativeIOContext;
154
139
  }, maxProbeSize?: number): Promise<InputFormat | null>;
155
140
  /**
156
- * A comma separated list of short names for the format.
141
+ * Format short name.
157
142
  *
158
- * Direct mapping to AVInputFormat->name
143
+ * Short identifier for the format (e.g., 'mp4', 'mkv').
159
144
  *
160
- * @readonly
145
+ * Direct mapping to AVInputFormat->name.
161
146
  */
162
147
  get name(): string | null;
163
148
  /**
164
- * Descriptive name for the format.
149
+ * Format long name.
165
150
  *
166
- * Direct mapping to AVInputFormat->long_name
151
+ * Human-readable description of the format.
167
152
  *
168
- * Meant to be more human-readable than the short name.
169
- * @readonly
153
+ * Direct mapping to AVInputFormat->long_name.
170
154
  */
171
155
  get longName(): string | null;
172
156
  /**
173
- * Comma-separated list of file extensions.
157
+ * File extensions.
174
158
  *
175
- * Direct mapping to AVInputFormat->extensions
159
+ * Comma-separated list of file extensions for this format.
176
160
  *
177
- * If extensions are defined, then no probe is done.
178
- * @readonly
161
+ * Direct mapping to AVInputFormat->extensions.
179
162
  */
180
163
  get extensions(): string | null;
181
164
  /**
182
- * Comma-separated list of mime types.
165
+ * MIME type.
183
166
  *
184
- * Direct mapping to AVInputFormat->mime_type
167
+ * MIME type(s) associated with this format.
185
168
  *
186
- * @readonly
169
+ * Direct mapping to AVInputFormat->mime_type.
187
170
  */
188
171
  get mimeType(): string | null;
189
172
  /**
190
173
  * Format flags.
191
174
  *
192
- * Direct mapping to AVInputFormat->flags
193
- *
194
- * Combination of AVFMT_* flags:
195
- * - AVFMT_NOFILE: No file is opened
196
- * - AVFMT_NEEDNUMBER: Needs '%d' in filename
197
- * - AVFMT_SHOW_IDS: Show format stream IDs
198
- * - AVFMT_GLOBALHEADER: Format wants global headers
199
- * - AVFMT_NOTIMESTAMPS: Format does not need/have timestamps
200
- * - AVFMT_GENERIC_INDEX: Use generic index building code
201
- * - AVFMT_TS_DISCONT: Format allows timestamp discontinuities
202
- * - AVFMT_NOBINSEARCH: Format does not allow seeking by bytes
203
- * - AVFMT_NOGENSEARCH: Format does not allow seeking by timestamp
204
- * - AVFMT_NO_BYTE_SEEK: Format does not allow seeking by bytes
205
- * - AVFMT_SEEK_TO_PTS: Seeking is based on PTS
206
- * @readonly
175
+ * Combination of AVFMT_* flags indicating format capabilities.
176
+ *
177
+ * Direct mapping to AVInputFormat->flags.
207
178
  */
208
179
  get flags(): AVFormatFlag;
209
180
  /**
210
- * Get the native FFmpeg AVInputFormat pointer.
181
+ * Get the underlying native InputFormat object.
182
+ *
183
+ * @returns The native InputFormat binding object
211
184
  *
212
- * @internal For use by other wrapper classes
213
- * @returns The underlying native input format object
185
+ * @internal
214
186
  */
215
187
  getNative(): NativeInputFormat;
216
188
  }
@@ -1,10 +1,11 @@
1
1
  import { bindings } from './binding.js';
2
2
  /**
3
- * Input format (demuxer) descriptor.
3
+ * Input format descriptor for demuxing media files.
4
4
  *
5
- * Describes a supported input container format for demuxing.
6
- * Provides format information like name, extensions, and capabilities.
7
- * These are read-only format descriptors managed by FFmpeg.
5
+ * Represents a demuxer that can read and parse specific media container formats.
6
+ * Each format handles specific file types (e.g., MP4, MKV, AVI) and knows how to
7
+ * extract streams and packets from them. Used to identify and open media files
8
+ * for reading.
8
9
  *
9
10
  * Direct mapping to FFmpeg's AVInputFormat.
10
11
  *
@@ -12,82 +13,65 @@ import { bindings } from './binding.js';
12
13
  * ```typescript
13
14
  * import { InputFormat, FormatContext, FFmpegError } from 'node-av';
14
15
  *
15
- * // Find a specific input format
16
+ * // Find format by name
16
17
  * const mp4Format = InputFormat.findInputFormat('mp4');
17
18
  * if (mp4Format) {
18
- * console.log(`Format: ${mp4Format.longName}`);
19
+ * console.log(`Format: ${mp4Format.name}`);
20
+ * console.log(`Description: ${mp4Format.longName}`);
19
21
  * console.log(`Extensions: ${mp4Format.extensions}`);
20
22
  * }
21
23
  *
22
- * // Use with FormatContext
23
- * const ctx = new FormatContext();
24
- * ctx.allocContext();
24
+ * // Probe format from file data
25
+ * const fileData = Buffer.from([...]); // First few KB of file
26
+ * const detectedFormat = InputFormat.probe(fileData, 'video.mp4');
27
+ * if (detectedFormat) {
28
+ * console.log(`Detected: ${detectedFormat.name}`);
29
+ * }
25
30
  *
26
- * // Force a specific input format
27
- * const movFormat = InputFormat.findInputFormat('mov');
28
- * const ret = await ctx.openInput('video.dat', movFormat, null);
31
+ * // Use with format context
32
+ * const formatContext = new FormatContext();
33
+ * formatContext.inputFormat = mp4Format;
34
+ * const ret = await formatContext.openInput('video.mp4');
29
35
  * FFmpegError.throwIfError(ret, 'openInput');
30
36
  * ```
31
37
  *
32
- * @see {@link FormatContext} For using input formats
33
- * @see {@link OutputFormat} For output formats
38
+ * @see [AVInputFormat](https://ffmpeg.org/doxygen/trunk/structAVInputFormat.html) - FFmpeg Doxygen
39
+ * @see {@link FormatContext} For using formats to open files
40
+ * @see {@link OutputFormat} For muxing formats
34
41
  */
35
42
  export class InputFormat {
36
43
  native;
37
44
  /**
38
- * Constructor is internal - use static factory methods.
39
- *
40
- * InputFormats are obtained via static methods, not created directly.
41
- * FFmpeg manages these format descriptors internally.
42
- *
45
+ * @param native - The native input format instance
43
46
  * @internal
44
- *
45
- * @param native - Native AVInputFormat to wrap
46
- *
47
- * @example
48
- * ```typescript
49
- * import { InputFormat } from 'node-av';
50
- *
51
- * // Don't use constructor directly
52
- * // const format = new InputFormat(); // Wrong
53
- *
54
- * // Use static factory methods instead
55
- * const format = InputFormat.findInputFormat('mp4'); // Correct
56
- * ```
57
47
  */
58
48
  constructor(native) {
59
49
  this.native = native;
60
50
  }
61
51
  /**
62
- * Find a registered input format with matching name.
52
+ * Find input format by short name.
63
53
  *
64
- * Searches FFmpeg's registered demuxers by short name.
65
- * Useful for forcing a specific format when auto-detection fails.
54
+ * Searches for a demuxer by its short name identifier.
66
55
  *
67
- * Direct mapping to av_find_input_format()
56
+ * Direct mapping to av_find_input_format().
68
57
  *
69
- * @param shortName - Short name of the format (e.g., 'mp4', 'mov', 'avi')
70
- *
71
- * @returns InputFormat if found, null otherwise
58
+ * @param shortName - Format short name (e.g., 'mp4', 'mkv', 'avi')
59
+ * @returns Input format if found, null otherwise
72
60
  *
73
61
  * @example
74
62
  * ```typescript
75
- * import { InputFormat, FormatContext, FFmpegError } from 'node-av';
76
- *
77
- * const format = InputFormat.findInputFormat('mp4');
78
- * if (format) {
79
- * console.log(`Found: ${format.longName}`);
80
- * }
81
- *
82
- * // Force specific format when opening
83
- * const movFormat = InputFormat.findInputFormat('mov');
84
- * if (movFormat) {
85
- * const ctx = new FormatContext();
86
- * ctx.allocContext();
87
- * const ret = await ctx.openInput('video.dat', movFormat, null);
88
- * FFmpegError.throwIfError(ret, 'openInput');
63
+ * // Find specific formats
64
+ * const mp4 = InputFormat.findInputFormat('mp4');
65
+ * const mkv = InputFormat.findInputFormat('matroska');
66
+ * const avi = InputFormat.findInputFormat('avi');
67
+ *
68
+ * // Check if format is available
69
+ * if (!mp4) {
70
+ * console.error('MP4 format not available');
89
71
  * }
90
72
  * ```
73
+ *
74
+ * @see {@link probe} To auto-detect format
91
75
  */
92
76
  static findInputFormat(shortName) {
93
77
  const native = bindings.InputFormat.findInputFormat(shortName);
@@ -97,31 +81,34 @@ export class InputFormat {
97
81
  return new InputFormat(native);
98
82
  }
99
83
  /**
100
- * Probe input format from buffer data.
84
+ * Probe format from buffer data.
101
85
  *
102
- * Attempts to detect the input format based on buffer contents.
103
- * This is a synchronous operation that analyzes buffer data to identify the format.
86
+ * Analyzes buffer content to determine the media format.
87
+ * Optionally uses filename for additional format hints.
104
88
  *
105
- * Direct mapping to av_probe_input_format3()
89
+ * Direct mapping to av_probe_input_format2().
106
90
  *
107
- * @param buffer - Buffer containing media data to probe
108
- * @param filename - Optional filename hint to aid detection
109
- *
110
- * @returns InputFormat if detected, null otherwise
91
+ * @param buffer - Buffer containing file header/start
92
+ * @param filename - Optional filename for format hints
93
+ * @returns Detected format, or null if not recognized
111
94
  *
112
95
  * @example
113
96
  * ```typescript
114
- * import { InputFormat } from 'node-av';
115
97
  * import { readFileSync } from 'fs';
116
98
  *
117
- * // Read first few KB of a media file
118
- * const buffer = readFileSync('video.mp4', { length: 4096 });
119
- * const format = InputFormat.probe(buffer, 'video.mp4');
99
+ * // Read first 4KB for probing
100
+ * const data = readFileSync('video.mp4').subarray(0, 4096);
101
+ * const format = InputFormat.probe(data, 'video.mp4');
120
102
  *
121
103
  * if (format) {
122
- * console.log(`Detected format: ${format.longName}`);
104
+ * console.log(`Detected format: ${format.name}`);
105
+ * } else {
106
+ * console.error('Unknown format');
123
107
  * }
124
108
  * ```
109
+ *
110
+ * @see {@link probeBuffer} For IO context probing
111
+ * @see {@link findInputFormat} To get format by name
125
112
  */
126
113
  static probe(buffer, filename) {
127
114
  const native = bindings.InputFormat.probe(buffer, filename);
@@ -131,36 +118,34 @@ export class InputFormat {
131
118
  return new InputFormat(native);
132
119
  }
133
120
  /**
134
- * Probe input format from IOContext buffer.
135
- *
136
- * Attempts to detect the input format by reading from an IOContext.
137
- * This is an asynchronous operation that reads data from the IOContext to identify the format.
138
- * The IOContext position may be changed during probing.
121
+ * Probe format from IO context.
139
122
  *
140
- * Direct mapping to av_probe_input_buffer2()
123
+ * Reads data from an IO context to determine format.
124
+ * Useful for custom IO scenarios and network streams.
141
125
  *
142
- * @param ioContext - IOContext to read data from for probing
143
- * @param maxProbeSize - Maximum bytes to read for probing (0 for default)
126
+ * Direct mapping to av_probe_input_buffer2().
144
127
  *
145
- * @returns Promise resolving to InputFormat if detected, null otherwise
128
+ * @param ioContext - IO context to read from
129
+ * @param ioContext.getNative - Method to get native IO context
130
+ * @param maxProbeSize - Maximum bytes to read for probing
131
+ * @returns Detected format, or null if not recognized
146
132
  *
147
133
  * @example
148
134
  * ```typescript
149
- * import { InputFormat, IOContext } from 'node-av';
135
+ * import { IOContext } from 'node-av';
150
136
  *
151
- * // Open an IOContext
152
- * const io = new IOContext();
153
- * await io.open2('video.mp4', AVIO_FLAG_READ);
154
- *
155
- * // Probe the format
156
- * const format = await InputFormat.probeBuffer(io);
137
+ * // Create custom IO context
138
+ * const ioContext = new IOContext();
139
+ * // ... configure IO context ...
157
140
  *
141
+ * // Probe format
142
+ * const format = await InputFormat.probeBuffer(ioContext, 32768);
158
143
  * if (format) {
159
- * console.log(`Detected format: ${format.longName}`);
144
+ * console.log(`Stream format: ${format.name}`);
160
145
  * }
161
- *
162
- * await io.closep();
163
146
  * ```
147
+ *
148
+ * @see {@link probe} For buffer probing
164
149
  */
165
150
  static async probeBuffer(ioContext, maxProbeSize) {
166
151
  const native = await bindings.InputFormat.probeBuffer(ioContext.getNative(), maxProbeSize);
@@ -170,43 +155,41 @@ export class InputFormat {
170
155
  return new InputFormat(native);
171
156
  }
172
157
  /**
173
- * A comma separated list of short names for the format.
158
+ * Format short name.
174
159
  *
175
- * Direct mapping to AVInputFormat->name
160
+ * Short identifier for the format (e.g., 'mp4', 'mkv').
176
161
  *
177
- * @readonly
162
+ * Direct mapping to AVInputFormat->name.
178
163
  */
179
164
  get name() {
180
165
  return this.native.name;
181
166
  }
182
167
  /**
183
- * Descriptive name for the format.
168
+ * Format long name.
184
169
  *
185
- * Direct mapping to AVInputFormat->long_name
170
+ * Human-readable description of the format.
186
171
  *
187
- * Meant to be more human-readable than the short name.
188
- * @readonly
172
+ * Direct mapping to AVInputFormat->long_name.
189
173
  */
190
174
  get longName() {
191
175
  return this.native.longName;
192
176
  }
193
177
  /**
194
- * Comma-separated list of file extensions.
178
+ * File extensions.
195
179
  *
196
- * Direct mapping to AVInputFormat->extensions
180
+ * Comma-separated list of file extensions for this format.
197
181
  *
198
- * If extensions are defined, then no probe is done.
199
- * @readonly
182
+ * Direct mapping to AVInputFormat->extensions.
200
183
  */
201
184
  get extensions() {
202
185
  return this.native.extensions;
203
186
  }
204
187
  /**
205
- * Comma-separated list of mime types.
188
+ * MIME type.
206
189
  *
207
- * Direct mapping to AVInputFormat->mime_type
190
+ * MIME type(s) associated with this format.
208
191
  *
209
- * @readonly
192
+ * Direct mapping to AVInputFormat->mime_type.
210
193
  */
211
194
  get mimeType() {
212
195
  return this.native.mimeType;
@@ -214,30 +197,19 @@ export class InputFormat {
214
197
  /**
215
198
  * Format flags.
216
199
  *
217
- * Direct mapping to AVInputFormat->flags
218
- *
219
- * Combination of AVFMT_* flags:
220
- * - AVFMT_NOFILE: No file is opened
221
- * - AVFMT_NEEDNUMBER: Needs '%d' in filename
222
- * - AVFMT_SHOW_IDS: Show format stream IDs
223
- * - AVFMT_GLOBALHEADER: Format wants global headers
224
- * - AVFMT_NOTIMESTAMPS: Format does not need/have timestamps
225
- * - AVFMT_GENERIC_INDEX: Use generic index building code
226
- * - AVFMT_TS_DISCONT: Format allows timestamp discontinuities
227
- * - AVFMT_NOBINSEARCH: Format does not allow seeking by bytes
228
- * - AVFMT_NOGENSEARCH: Format does not allow seeking by timestamp
229
- * - AVFMT_NO_BYTE_SEEK: Format does not allow seeking by bytes
230
- * - AVFMT_SEEK_TO_PTS: Seeking is based on PTS
231
- * @readonly
200
+ * Combination of AVFMT_* flags indicating format capabilities.
201
+ *
202
+ * Direct mapping to AVInputFormat->flags.
232
203
  */
233
204
  get flags() {
234
205
  return this.native.flags;
235
206
  }
236
207
  /**
237
- * Get the native FFmpeg AVInputFormat pointer.
208
+ * Get the underlying native InputFormat object.
209
+ *
210
+ * @returns The native InputFormat binding object
238
211
  *
239
- * @internal For use by other wrapper classes
240
- * @returns The underlying native input format object
212
+ * @internal
241
213
  */
242
214
  getNative() {
243
215
  return this.native;
@@ -1 +1 @@
1
- {"version":3,"file":"input-format.js","sourceRoot":"","sources":["../../src/lib/input-format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAgCG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAoB;IAElC;;;;;;;;;;;;;;;;;;;;OAoBG;IACH,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA8BG;IACH,MAAM,CAAC,eAAe,CAAC,SAAiB;QACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;OA0BG;IACH,MAAM,CAAC,KAAK,CAAC,MAAc,EAAE,QAAiB;QAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA+BG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,SAA2C,EAAE,YAAqB;QACzF,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,YAAY,CAAC,CAAC;QAC3F,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED;;;;;;;OAOG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED;;;;;;;;;;;;;;;;;;OAkBG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED;;;;;OAKG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}
1
+ {"version":3,"file":"input-format.js","sourceRoot":"","sources":["../../src/lib/input-format.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKxC;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAuCG;AACH,MAAM,OAAO,WAAW;IACd,MAAM,CAAoB;IAElC;;;OAGG;IACH,YAAY,MAAyB;QACnC,IAAI,CAAC,MAAM,GAAG,MAAM,CAAC;IACvB,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;OAwBG;IACH,MAAM,CAAC,eAAe,CAAC,SAAiB;QACtC,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,eAAe,CAAC,SAAS,CAAC,CAAC;QAC/D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,KAAK,CAAC,MAAc,EAAE,QAAiB;QAC5C,MAAM,MAAM,GAAG,QAAQ,CAAC,WAAW,CAAC,KAAK,CAAC,MAAM,EAAE,QAAQ,CAAC,CAAC;QAC5D,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;;;;;;;;;;;;;;;;;;;;;;;;OA6BG;IACH,MAAM,CAAC,KAAK,CAAC,WAAW,CAAC,SAA2C,EAAE,YAAqB;QACzF,MAAM,MAAM,GAAG,MAAM,QAAQ,CAAC,WAAW,CAAC,WAAW,CAAC,SAAS,CAAC,SAAS,EAAE,EAAE,YAAY,CAAC,CAAC;QAC3F,IAAI,CAAC,MAAM,EAAE,CAAC;YACZ,OAAO,IAAI,CAAC;QACd,CAAC;QACD,OAAO,IAAI,WAAW,CAAC,MAAM,CAAC,CAAC;IACjC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,IAAI;QACN,OAAO,IAAI,CAAC,MAAM,CAAC,IAAI,CAAC;IAC1B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,UAAU;QACZ,OAAO,IAAI,CAAC,MAAM,CAAC,UAAU,CAAC;IAChC,CAAC;IAED;;;;;;OAMG;IACH,IAAI,QAAQ;QACV,OAAO,IAAI,CAAC,MAAM,CAAC,QAAQ,CAAC;IAC9B,CAAC;IAED;;;;;;OAMG;IACH,IAAI,KAAK;QACP,OAAO,IAAI,CAAC,MAAM,CAAC,KAAK,CAAC;IAC3B,CAAC;IAED;;;;;;OAMG;IACH,SAAS;QACP,OAAO,IAAI,CAAC,MAAM,CAAC;IACrB,CAAC;CACF"}