exifreader 4.39.1 → 4.40.1

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.
package/README.md CHANGED
@@ -7,6 +7,10 @@ browser or from Node. Supports JPEG, JPEG XL, TIFF, PNG, HEIC, AVIF, WebP, and
7
7
  GIF files with Exif, IPTC, XMP, ICC, MPF, and more metadata (depending on file
8
8
  type).
9
9
 
10
+ If you use the `length: 'auto'` option, ExifReader reads only the bytes
11
+ that contain metadata, **well under 1 ms per file** for typical phone JPEGs
12
+ and **over 95% less bandwidth**.
13
+
10
14
  ExifReader is highly and easily configurable and the resulting bundle can be as
11
15
  small as **~4 KiB** (gzipped) if you're only interested in a few tags (e.g. date
12
16
  and/or GPS values).
@@ -197,6 +201,319 @@ Where `fileBuffer` is one of
197
201
  See the [examples site](https://mattiasw.github.io/ExifReader/) for more
198
202
  directions on how to use the library.
199
203
 
204
+ #### Grouping
205
+
206
+ By default, Exif, IPTC and XMP tags are grouped together. This means that if
207
+ e.g. `Orientation` exists in both Exif and XMP, the first value (Exif) will be
208
+ overwritten by the second (XMP). If you need to separate between these values,
209
+ pass in an options object with the property `expanded` set to `true`:
210
+
211
+ ```javascript
212
+ const tags = ExifReader.load(fileBuffer, {expanded: true});
213
+ ```
214
+
215
+ #### Filtering tags (includeTags / excludeTags)
216
+
217
+ You can filter which tags are returned by using `includeTags` and/or
218
+ `excludeTags`.
219
+
220
+ - If `includeTags` is provided, it uses an **include-pattern**: only the groups
221
+ you specify will be included in the output.
222
+ - `excludeTags` can be used alone to remove tags/groups while keeping everything
223
+ else.
224
+ - If a group is specified in both `includeTags` and `excludeTags`, `excludeTags`
225
+ for that group will be ignored.
226
+ - An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
227
+ excluding that group. The group will not be returned and ExifReader will skip
228
+ parsing it.
229
+
230
+ **Examples**
231
+
232
+ Exclude a few tags in the Exif group:
233
+
234
+ ```javascript
235
+ const tags = ExifReader.load(fileBuffer, {
236
+ excludeTags: {
237
+ exif: ['MakerNote', 0x9286],
238
+ }
239
+ });
240
+ ```
241
+
242
+ Only return XMP tags (and exclude everything else):
243
+
244
+ ```javascript
245
+ const tags = ExifReader.load(fileBuffer, {
246
+ includeTags: {
247
+ xmp: true,
248
+ }
249
+ });
250
+ ```
251
+
252
+ **Filtering groups**
253
+
254
+ The group keys follow the same concept as the output when `expanded: true` is
255
+ used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
256
+
257
+ For PNG, filtering is done with the `png` group only. (The `pngFile` and
258
+ `pngText` groups exist in `expanded` output today, but `png` is the filtering
259
+ key and those groups will be deprecated later.)
260
+
261
+ | Group key | Description | Supports IDs |
262
+ | ------------- | ------------------------------------------------ | ------------ |
263
+ | `exif` | Exif tags (including GPS IFD, interoperability). | yes |
264
+ | `iptc` | IPTC tags. | yes |
265
+ | `xmp` | XMP tags. | no |
266
+ | `icc` | ICC profile tags. | no |
267
+ | `photoshop` | Photoshop resource tags. | yes |
268
+ | `makerNotes` | MakerNote tags (e.g. Canon/Pentax). | yes |
269
+ | `mpf` | MPF tags. | yes |
270
+ | `file` | JPEG file details and `FileType`. | no |
271
+ | `jfif` | JFIF tags. | no |
272
+ | `png` | PNG header, chunk, and text tags. | no |
273
+ | `riff` | WebP (RIFF) tags. | no |
274
+ | `gif` | GIF tags. | no |
275
+ | `gps` | Computed GPS group (only when `expanded: true`). | no |
276
+ | `composite` | Composite tags (e.g. FieldOfView). | no |
277
+ | `thumbnail` | Top-level `Thumbnail` output. | no |
278
+
279
+ **Important: dependency tags**
280
+
281
+ Some tags act as pointers or containers to other metadata. Excluding them can
282
+ cause other tags or entire groups to disappear. Some important examples:
283
+
284
+ - `Exif IFD Pointer`, `GPS Info IFD Pointer`, `Interoperability IFD Pointer`
285
+ - `IPTC-NAA` (TIFF embedded IPTC), `ApplicationNotes` (TIFF embedded XMP),
286
+ `ICC_Profile` (TIFF embedded ICC)
287
+ - `MakerNote` and `Make` (maker note parsing)
288
+ - `ImageSourceData` and `PhotoshopSettings` (Photoshop parsing)
289
+ - `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` (thumbnails)
290
+
291
+ **NOTE:** When using `includeTags`, you **do not** have to list these dependency
292
+ tags. ExifReader will automatically include the required pointer/container tags
293
+ needed to find and parse the groups you requested. This section mainly matters
294
+ when using `excludeTags`.
295
+
296
+ Note that XMP and ICC tags are parsed from full metadata blocks, so ExifReader
297
+ cannot skip parsing individual XMP/ICC tags based on selectors. The returned
298
+ output is still filtered.
299
+
300
+ #### Unknown tags
301
+
302
+ Tags that are unknown, either because they have been excluded by making a custom
303
+ build or they are yet to be added into ExifReader, are by default not included
304
+ in the output. If you need to see them there is an option that can be passed in:
305
+
306
+ ```javascript
307
+ const tags = ExifReader.load(fileBuffer, {includeUnknown: true});
308
+ ```
309
+
310
+ If you discover an unknown tag that should be handled by ExifReader, please
311
+ reach out by filing an issue.
312
+
313
+ #### Computed tag values (opt-in)
314
+
315
+ ExifReader exposes three different values per Exif tag:
316
+
317
+ - **`value`**: A stable, raw-ish value that mirrors how the tag is stored in the
318
+ file.
319
+ - **`description`**: A human-friendly value meant for display.
320
+ - **`computed`**: An opt-in, type-aware value. This will often be the same as
321
+ `value` except for RATIONAL/SRATIONAL and ASCII tags.
322
+
323
+ Enable the `computed` value by passing `computed: true` in the options:
324
+
325
+ ```javascript
326
+ const tags = ExifReader.load(fileBuffer, {computed: true});
327
+
328
+ const make = tags['Make'].computed; // e.g. "Apple"
329
+ const xResolution = tags['XResolution'].computed; // e.g. 72
330
+ ```
331
+
332
+ `computed` is only added for tags parsed from TIFF IFD structures (Exif/GPS/etc,
333
+ including maker notes, MPF, and the Thumbnail IFD). It is not currently added to
334
+ XMP/IPTC/ICC tags or PNG text tags.
335
+
336
+ The `computed` conversion rules are based on the TIFF tag type:
337
+
338
+ - **ASCII**: If `value` contains a single string, `computed` is that string.
339
+ Otherwise `computed` is a string array.
340
+ - **RATIONAL / SRATIONAL**: `computed` is a number (or an array of numbers).
341
+ Division by zero yields `null`.
342
+ - **All other types**: `computed` equals `value`.
343
+
344
+ Note that `computed` may evolve in minor versions as the feature matures. If you
345
+ need a value with the strongest stability guarantees, prefer `value`.
346
+
347
+ #### Read only part of file
348
+
349
+ If you only want to read part of the image file you can use the `length` option:
350
+
351
+ ```javascript
352
+ const tags = await ExifReader.load(filename, {length: 128 * 1024});
353
+ ```
354
+
355
+ This will load only the first 128 KiB of the file. This could be useful if you
356
+ know the metadata is located at the beginning of the file. Just be aware that
357
+ it's common for the metadata to be spread out over a larger area so please try
358
+ it out on your set of files to know if it's suitable for your situation.
359
+
360
+ Note that this option only works when ExifReader handles the loading of the
361
+ file. If e.g. an already loaded ArrayBuffer or Buffer is passed into ExifReader,
362
+ the whole file will already have been loaded into memory and it's too late.
363
+ More specifically the length option will work for 1. local files when running
364
+ through Node.js, 2. remote files when passing a URL, and 3. browser File objects
365
+ (e.g., from form file fields). For remote files accessed through a web browser,
366
+ make sure the remote server is either on the same origin (domain) as your script
367
+ or that the server is passing correct CORS headers, specifically allowing the
368
+ `Range` header.
369
+
370
+ #### Read only the metadata bytes (`length: 'auto'`)
371
+
372
+ When you want to download or store just enough of an image to extract its
373
+ metadata, without guessing a fixed `length`, pass `length: 'auto'`:
374
+
375
+ ```javascript
376
+ const tags = await ExifReader.load(url, {
377
+ length: 'auto',
378
+ expanded: true,
379
+ includeOffsets: true,
380
+ excludeTags: {mpf: true}, // skip embedded preview; see note below
381
+ });
382
+
383
+ tags.metadataRange.end // exact byte count needed for the metadata
384
+ tags.metadataRange.buffer // bytes [0, end), sliced from what we read.
385
+ // Same kind as the input (ArrayBuffer or
386
+ // Node Buffer). Save this to disk to keep
387
+ // only the metadata-bearing prefix.
388
+ tags.metadataRange.fetched // bytes actually read. May be greater than
389
+ // `end` because the loop reads in fixed-size
390
+ // chunks and so may read a little past `end`.
391
+ tags.metadataRange.requests // number of IO calls performed
392
+ ```
393
+
394
+ ExifReader fetches an initial 128 KiB prefix and parses it. Only if the
395
+ metadata extends further does it issue an HTTP `Range` request (or a
396
+ follow-up filesystem read / `File.slice`) for exactly the additional bytes
397
+ needed. Most files finish in a single request. HEIC/AVIF files where the
398
+ Exif/XMP `iloc` entries point near the end of the file typically take two.
399
+
400
+ `length: 'auto'` is supported for the four IO inputs:
401
+
402
+ - URL via browser `fetch` (uses HTTP `Range`)
403
+ - URL via Node `http(s)` (uses HTTP `Range`)
404
+ - Local file path via Node `fs`
405
+ - Browser `File` object via `File.slice`
406
+
407
+ It is also accepted for in-memory inputs (`ArrayBuffer`, `Buffer`,
408
+ `SharedArrayBuffer`, `DataView`) as a convenience. There is no IO loop to
409
+ run in that case, but `metadataRange.buffer` is still attached as the
410
+ trimmed slice of what you passed in.
411
+
412
+ Requirements and caveats:
413
+
414
+ - `expanded: true` and `includeOffsets: true` are required. Passing
415
+ `length: 'auto'` without them throws a clear error (at runtime, and also a
416
+ type error in TypeScript).
417
+ - The return is always a `Promise` because the loop is asynchronous.
418
+ - Not supported for plain TIFF or bare JPEG XL codestreams. They have no
419
+ leading metadata container, so the loop has no convergence signal and
420
+ will reject with an error.
421
+ - If the loop fails to converge in 4 iterations (very rare, defensive
422
+ bound for unknown-size HTTP responses or files whose parsers can't
423
+ bootstrap from a small prefix), ExifReader reads the rest of the file
424
+ and emits a single `console.warn`. Correctness is preserved. The
425
+ bandwidth savings are forfeit.
426
+
427
+ **Why `excludeTags: {mpf: true}` is in the example.** Most modern phone
428
+ cameras (and many DSLRs) emit JPEGs with a Multi-Picture-Format sub-image
429
+ preview embedded a few MB into the file. Without `excludeTags: {mpf:
430
+ true}` ExifReader treats those sub-images as part of the metadata range,
431
+ so `metadataRange.end` lands near EOF and `length: 'auto'` ends up
432
+ reading most of the file anyway. On a corpus of about 1.5 GiB of phone
433
+ photos this single option took `length: 'auto'` from a ~17% slowdown vs
434
+ a regular full read to a **6× speedup with 98% of bytes saved**. The
435
+ regular `tags.exif`, `tags.xmp`, `tags.icc`, `tags.gps` and the rest are
436
+ unaffected. Drop the option only if you actually need the
437
+ `tags.mpf.Images` array.
438
+
439
+ #### Locating metadata in the file (`includeOffsets`)
440
+
441
+ Pass `includeOffsets: true` together with `expanded: true` to learn where in
442
+ the file the metadata sits. Useful for persisting only the metadata-bearing
443
+ prefix of an image rather than the whole file. The resulting slice is enough
444
+ for re-extracting metadata with ExifReader, not for opening the slice as an
445
+ image.
446
+
447
+ ```javascript
448
+ const tags = ExifReader.load(fileBuffer, {expanded: true, includeOffsets: true});
449
+
450
+ tags.metadataRange.start // lowest block start (informational, can be deep
451
+ // into the file for HEIC/AVIF; do NOT use as a
452
+ // slice boundary, always slice from 0)
453
+ tags.metadataRange.end // exclusive end. Store bytes 0..end to keep all metadata
454
+ tags.metadataRange.complete // false when the input was truncated before all metadata
455
+ tags.metadataRange.blocks // [{type, start, end}, ...] sorted by start
456
+ ```
457
+
458
+ Offsets are byte indices into the data you passed in. `metadataRange` is
459
+ attached only when both `expanded: true` and `includeOffsets: true` are set,
460
+ so default and flat-mode output are unchanged.
461
+
462
+ Block `type` reuses the filtering-group vocabulary (`exif`, `iptc`, `xmp`,
463
+ `icc`, `mpf`, `jfif`, `file`, `png`, `riff`, `gif`), plus `mpfImage` for the
464
+ sub-images of an MPF Multi-Picture JPEG. The same type may appear more than
465
+ once (multi-chunk ICC, extended XMP), one entry per physical container.
466
+
467
+ Typical workflow:
468
+
469
+ ```javascript
470
+ const headChunk = await fetchFirstNBytes(url, 256 * 1024);
471
+ const tags = ExifReader.load(headChunk, {expanded: true, includeOffsets: true});
472
+
473
+ if (!tags.metadataRange.complete) {
474
+ // 256 KiB was not enough, fetch more
475
+ } else {
476
+ const minimalSlice = headChunk.slice(0, tags.metadataRange.end);
477
+ await uploadMetadata(minimalSlice);
478
+ }
479
+ ```
480
+
481
+ Notes and limitations:
482
+
483
+ - Not supported for plain TIFF or bare JPEG XL codestreams (no leading
484
+ metadata container). `metadataRange` is omitted in both cases.
485
+ - For JPEG XL containers, blocks cover the `Exif` and `xml ` boxes but not
486
+ the `jxlc`/`jxlp` codestream box (encoded image data, not metadata).
487
+ - `complete: true` means ExifReader did not detect truncation. For JPEG and
488
+ PNG it observed `SOS` or `IEND`, for standalone XMP it observed an
489
+ `<?xpacket end=?>` or `</x:xmpmeta>` token. For other formats it is
490
+ best-effort, a buffer ending cleanly between metadata segments can still
491
+ report `complete: true`. Non-standard trailers (JPEG-XT, post-SOS markers)
492
+ are never detected. Note the converse: re-parsing a slice produced by
493
+ `buffer.slice(0, metadataRange.end)` may report `complete: false` for
494
+ JPEG/PNG even though every metadata segment is intact, because the
495
+ slice ends before `SOS`/`IEND`. The block list and `tags.exif` etc. are
496
+ still complete in that case.
497
+ - Only the metadata segments ExifReader actively parses are present in
498
+ `blocks`. JPEG segments ExifReader does not currently extract tags from
499
+ (APP3-APP12, `COM` comments, JPEG-XT extensions) do not appear and are
500
+ not guaranteed to be preserved by a `0..end` slice. The slice is
501
+ enough to re-extract everything ExifReader itself reads, not to
502
+ preserve every byte a third-party tool might care about.
503
+ - For HEIC/AVIF, metadata can sit near the end of the file, so
504
+ `metadataRange.end` often lands close to the file size and trimming
505
+ saves little. The `icc` block here covers just the ICC profile bytes;
506
+ for JPEG/PNG/WebP it covers the full container wrapper.
507
+ - For MPF JPEGs, sub-images appear as `mpfImage` blocks and push `end`
508
+ toward the file size. If MPF parsing is suppressed by a tag filter (any
509
+ `excludeTags: {mpf: ...}` or `includeTags` that does not include `mpf`),
510
+ the `mpfImage` blocks are not emitted and `metadataRange.end` shrinks.
511
+ The parent `mpf` segment block always remains, since it is a real
512
+ metadata segment found during the header scan.
513
+ - Offsets come from length fields in the file. Treat `metadataRange.end`
514
+ and `block.end` as untrusted input. Clamp to your buffer length before
515
+ slicing, allocating, or issuing remote range requests.
516
+
200
517
  #### Asynchronous tags
201
518
 
202
519
  Some tags need to be parsed asynchronously. Currently this is the case for some
@@ -287,17 +604,6 @@ warning is logged via `console.warn`, and the rest of the tags are returned as
287
604
  usual. The limit applies to the built-in Compression Streams paths and to any
288
605
  result returned by a custom `brotli`/`deflate` function.
289
606
 
290
- #### Grouping
291
-
292
- By default, Exif, IPTC and XMP tags are grouped together. This means that if
293
- e.g. `Orientation` exists in both Exif and XMP, the first value (Exif) will be
294
- overwritten by the second (XMP). If you need to separate between these values,
295
- pass in an options object with the property `expanded` set to `true`:
296
-
297
- ```javascript
298
- const tags = ExifReader.load(fileBuffer, {expanded: true});
299
- ```
300
-
301
607
  #### Parsing XMP tags when not in a DOM environment
302
608
 
303
609
  When using for example Node.js or a web worker, there is no native
@@ -355,161 +661,6 @@ If you're having trouble getting the GPS location, see [this comment and
355
661
  thread](https://github.com/mattiasw/ExifReader/issues/177#issuecomment-1172228225)
356
662
  and the [GPS section below](#gps) for more details.
357
663
 
358
- #### Read only part of file
359
-
360
- If you only want to read part of the image file you can use the `length` option:
361
-
362
- ```javascript
363
- const tags = await ExifReader.load(filename, {length: 128 * 1024});
364
- ```
365
-
366
- This will load only the first 128 KiB of the file. This could be useful if you
367
- know the metadata is located at the beginning of the file. Just be aware that
368
- it's common for the metadata to be spread out over a larger area so please try
369
- it out on your set of files to know if it's suitable for your situation.
370
-
371
- Note that this option only works when ExifReader handles the loading of the
372
- file. If e.g. an already loaded ArrayBuffer or Buffer is passed into ExifReader,
373
- the whole file will already have been loaded into memory and it's too late.
374
- More specifically the length option will work for 1. local files when running
375
- through Node.js, 2. remote files when passing a URL, and 3. browser File objects
376
- (e.g., from form file fields). For remote files accessed through a web browser,
377
- make sure the remote server is either on the same origin (domain) as your script
378
- or that the server is passing correct CORS headers, specifically allowing the
379
- `Range` header.
380
-
381
- #### Unknown tags
382
-
383
- Tags that are unknown, either because they have been excluded by making a custom
384
- build or they are yet to be added into ExifReader, are by default not included
385
- in the output. If you need to see them there is an option that can be passed in:
386
-
387
- ```javascript
388
- const tags = ExifReader.load(fileBuffer, {includeUnknown: true});
389
- ```
390
-
391
- If you discover an unknown tag that should be handled by ExifReader, please
392
- reach out by filing an issue.
393
-
394
- #### Filtering tags (includeTags / excludeTags)
395
-
396
- You can filter which tags are returned by using `includeTags` and/or
397
- `excludeTags`.
398
-
399
- - If `includeTags` is provided, it uses an **include-pattern**: only the groups
400
- you specify will be included in the output.
401
- - `excludeTags` can be used alone to remove tags/groups while keeping everything
402
- else.
403
- - If a group is specified in both `includeTags` and `excludeTags`, `excludeTags`
404
- for that group will be ignored.
405
- - An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
406
- excluding that group. The group will not be returned and ExifReader will skip
407
- parsing it.
408
-
409
- **Examples**
410
-
411
- Exclude a few tags in the Exif group:
412
-
413
- ```javascript
414
- const tags = ExifReader.load(fileBuffer, {
415
- excludeTags: {
416
- exif: ['MakerNote', 0x9286],
417
- }
418
- });
419
- ```
420
-
421
- Only return XMP tags (and exclude everything else):
422
-
423
- ```javascript
424
- const tags = ExifReader.load(fileBuffer, {
425
- includeTags: {
426
- xmp: true,
427
- }
428
- });
429
- ```
430
-
431
- **Filtering groups**
432
-
433
- The group keys follow the same concept as the output when `expanded: true` is
434
- used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
435
-
436
- For PNG, filtering is done with the `png` group only. (The `pngFile` and
437
- `pngText` groups exist in `expanded` output today, but `png` is the filtering key
438
- and those groups will be deprecated later.)
439
-
440
- | Group key | Description | Supports IDs |
441
- | ------------- | ------------------------------------------------ | ------------ |
442
- | `exif` | Exif tags (including GPS IFD, interoperability). | yes |
443
- | `iptc` | IPTC tags. | yes |
444
- | `xmp` | XMP tags. | no |
445
- | `icc` | ICC profile tags. | no |
446
- | `photoshop` | Photoshop resource tags. | yes |
447
- | `makerNotes` | MakerNote tags (e.g. Canon/Pentax). | yes |
448
- | `mpf` | MPF tags. | yes |
449
- | `file` | JPEG file details and `FileType`. | no |
450
- | `jfif` | JFIF tags. | no |
451
- | `png` | PNG header, chunk, and text tags. | no |
452
- | `riff` | WebP (RIFF) tags. | no |
453
- | `gif` | GIF tags. | no |
454
- | `gps` | Computed GPS group (only when `expanded: true`). | no |
455
- | `composite` | Composite tags (e.g. FieldOfView). | no |
456
- | `thumbnail` | Top-level `Thumbnail` output. | no |
457
-
458
- **Important: dependency tags**
459
-
460
- Some tags act as pointers or containers to other metadata. Excluding them can
461
- cause other tags or entire groups to disappear. Some important examples:
462
-
463
- - `Exif IFD Pointer`, `GPS Info IFD Pointer`, `Interoperability IFD Pointer`
464
- - `IPTC-NAA` (TIFF embedded IPTC), `ApplicationNotes` (TIFF embedded XMP),
465
- `ICC_Profile` (TIFF embedded ICC)
466
- - `MakerNote` and `Make` (maker note parsing)
467
- - `ImageSourceData` and `PhotoshopSettings` (Photoshop parsing)
468
- - `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` (thumbnails)
469
-
470
- **NOTE:** When using `includeTags`, you **do not** have to list these dependency
471
- tags. ExifReader will automatically include the required pointer/container tags
472
- needed to find and parse the groups you requested. This section mainly matters
473
- when using `excludeTags`.
474
-
475
- Note that XMP and ICC tags are parsed from full metadata blocks, so ExifReader
476
- cannot skip parsing individual XMP/ICC tags based on selectors. The returned
477
- output is still filtered.
478
-
479
- #### Computed tag values (opt-in)
480
-
481
- ExifReader exposes three different values per Exif tag:
482
-
483
- - **`value`**: A stable, raw-ish value that mirrors how the tag is stored in the
484
- file.
485
- - **`description`**: A human-friendly value meant for display.
486
- - **`computed`**: An opt-in, type-aware value. This will often be the same as
487
- `value` except for RATIONAL/SRATIONAL and ASCII tags.
488
-
489
- Enable the `computed` value by passing `computed: true` in the options:
490
-
491
- ```javascript
492
- const tags = ExifReader.load(fileBuffer, {computed: true});
493
-
494
- const make = tags['Make'].computed; // e.g. "Apple"
495
- const xResolution = tags['XResolution'].computed; // e.g. 72
496
- ```
497
-
498
- `computed` is only added for tags parsed from TIFF IFD structures (Exif/GPS/etc,
499
- including maker notes, MPF, and the Thumbnail IFD). It is not currently added to
500
- XMP/IPTC/ICC tags or PNG text tags.
501
-
502
- The `computed` conversion rules are based on the TIFF tag type:
503
-
504
- - **ASCII**: If `value` contains a single string, `computed` is that string.
505
- Otherwise `computed` is a string array.
506
- - **RATIONAL / SRATIONAL**: `computed` is a number (or an array of numbers).
507
- Division by zero yields `null`.
508
- - **All other types**: `computed` equals `value`.
509
-
510
- Note that `computed` may evolve in minor versions as the feature matures. If you
511
- need a value with the strongest stability guarantees, prefer `value`.
512
-
513
664
  ### GPS
514
665
 
515
666
  If `expanded: true` is specified in the options, there will be a `gps` group.
@@ -748,6 +899,13 @@ Tips
748
899
  possibly Exif too if they come in an irregular order) so please check if
749
900
  this optimization fits your use case. Use the `length` option to only read
750
901
  the beginning of the file. See above for more details on that.
902
+ - Excluding MPF (Multi-Picture Format) makes a big difference for phone
903
+ photos. Modern phone JPEGs embed a sub-image preview a few MB into the
904
+ file. If you do not need it, pass `excludeTags: {mpf: true}`. This is
905
+ especially impactful when combined with `length: 'auto'` (multi-x
906
+ speedup, see that section), but it also lets a numeric `length`
907
+ boundary land well before the sub-image. Regular Exif/XMP/ICC tags are
908
+ unaffected.
751
909
 
752
910
  Known Limitations
753
911
  -----------------
@@ -0,0 +1,171 @@
1
+ /* This Source Code Form is subject to the terms of the Mozilla Public
2
+ * License, v. 2.0. If a copy of the MPL was not distributed with this
3
+ * file, You can obtain one at https://mozilla.org/MPL/2.0/. */
4
+
5
+ /* eslint-disable no-console */
6
+
7
+ const fs = require('fs');
8
+ const path = require('path');
9
+
10
+ const MIB = 1024 * 1024;
11
+
12
+ main();
13
+
14
+ function main() {
15
+ const args = process.argv.slice(2);
16
+ const helpRequested = args.includes('-h') || args.includes('--help');
17
+ if (helpRequested || args.length !== 2) {
18
+ printHelp();
19
+ process.exit(helpRequested ? 0 : 1);
20
+ }
21
+
22
+ const before = readReport(args[0]);
23
+ const after = readReport(args[1]);
24
+
25
+ console.log(`Diff: ${shortPath(args[0])} → ${shortPath(args[1])}`);
26
+ console.log(`Mode: before=${describeMode(before)} after=${describeMode(after)}`);
27
+ console.log('');
28
+
29
+ const byFormat = joinByFormat(before, after);
30
+ printFormatDiff(byFormat);
31
+
32
+ console.log('');
33
+ printOverallDiff(before, after);
34
+ }
35
+
36
+ function printHelp() {
37
+ console.log(`Usage: node bin/profile-diff.js <before.json> <after.json>
38
+
39
+ Compares two JSON reports produced by bin/profile.js. Per-format and overall
40
+ deltas in mean parse time and (when --length-auto was used) bytes read.
41
+
42
+ Recommended workflow:
43
+ node bin/profile.js --include-io -n 100 --probe-bytes --json \\
44
+ > .profile-results/baseline.json
45
+ node bin/profile.js --include-io -n 100 --length-auto --json \\
46
+ > .profile-results/after.json
47
+ node bin/profile-diff.js .profile-results/baseline.json .profile-results/after.json
48
+ `);
49
+ }
50
+
51
+ function readReport(p) {
52
+ try {
53
+ return JSON.parse(fs.readFileSync(p, 'utf8'));
54
+ } catch (error) {
55
+ console.error(`Failed to read ${p}: ${error.message || error}`);
56
+ process.exit(1);
57
+ }
58
+ }
59
+
60
+ function shortPath(p) {
61
+ const cwd = process.cwd();
62
+ return p.startsWith(cwd) ? path.relative(cwd, p) : p;
63
+ }
64
+
65
+ function describeMode(report) {
66
+ const o = report.options || {};
67
+ const parts = [];
68
+ parts.push(o.includeIo ? 'parse+IO' : 'parse-only');
69
+ if (o.lengthAuto) {
70
+ parts.push('length:auto');
71
+ }
72
+ if (o.excludeMpf) {
73
+ parts.push('no-mpf');
74
+ }
75
+ if (o.probeBytes) {
76
+ parts.push('probe');
77
+ }
78
+ parts.push(`n=${o.iterations}`);
79
+ return parts.join(' ');
80
+ }
81
+
82
+ function joinByFormat(before, after) {
83
+ const beforeByFmt = new Map();
84
+ for (const f of before.formats) {
85
+ beforeByFmt.set(f.format, f);
86
+ }
87
+ const out = [];
88
+ for (const a of after.formats) {
89
+ const b = beforeByFmt.get(a.format) || null;
90
+ out.push({format: a.format, before: b, after: a});
91
+ }
92
+ return out;
93
+ }
94
+
95
+ function printFormatDiff(rows) {
96
+ const headers = [
97
+ 'format', 'files', 'before-ms', 'after-ms', 'speedup',
98
+ 'before-MiB-read', 'after-MiB-read', 'bytes-saved'
99
+ ];
100
+ const tableRows = rows.map((r) => {
101
+ const beforeMs = r.before ? r.before.meanMs : null;
102
+ const afterMs = r.after ? r.after.meanMs : null;
103
+ const speedup = (beforeMs && afterMs && afterMs > 0) ? (beforeMs / afterMs) : null;
104
+ const beforeMiB = r.before ? r.before.bytes / MIB : null;
105
+ const afterFetchedRatio = (r.after && typeof r.after.fetchedRatio === 'number') ? r.after.fetchedRatio : null;
106
+ const afterMiB = (afterFetchedRatio !== null && r.after) ? (r.after.bytes * afterFetchedRatio) / MIB : null;
107
+ const saved = (beforeMiB !== null && afterMiB !== null && beforeMiB > 0) ? 1 - (afterMiB / beforeMiB) : null;
108
+ return [
109
+ r.format,
110
+ String((r.after && r.after.count) || 0),
111
+ beforeMs === null ? '-' : beforeMs.toFixed(2),
112
+ afterMs === null ? '-' : afterMs.toFixed(2),
113
+ speedup === null ? '-' : speedup.toFixed(2) + 'x',
114
+ beforeMiB === null ? '-' : beforeMiB.toFixed(1),
115
+ afterMiB === null ? '-' : afterMiB.toFixed(1),
116
+ saved === null ? '-' : (saved * 100).toFixed(1) + '%',
117
+ ];
118
+ });
119
+ printTable(headers, tableRows);
120
+ }
121
+
122
+ function printOverallDiff(before, after) {
123
+ const b = before.overall || {};
124
+ const a = after.overall || {};
125
+ const beforeMs = b.totalTime;
126
+ const afterMs = a.totalTime;
127
+ const speedup = (beforeMs && afterMs && afterMs > 0) ? (beforeMs / afterMs) : null;
128
+ const beforeMiB = (b.totalBytes || 0) / MIB;
129
+ const afterMiB = (typeof a.fetchedTotal === 'number') ? a.fetchedTotal / MIB : beforeMiB;
130
+ const saved = (beforeMiB > 0) ? 1 - (afterMiB / beforeMiB) : 0;
131
+
132
+ console.log(`Overall: ${formatMs(beforeMs)} → ${formatMs(afterMs)} (${speedup === null ? '-' : speedup.toFixed(2) + 'x'} speedup)`);
133
+ if (typeof a.fetchedTotal === 'number') {
134
+ console.log(`Bytes: ${beforeMiB.toFixed(1)} MiB → ${afterMiB.toFixed(1)} MiB (${(saved * 100).toFixed(1)}% saved)`);
135
+ if (typeof a.requestsMean === 'number') {
136
+ console.log(`Requests: ${a.requestsMean.toFixed(2)} per file on average across ${a.fetchedFiles} files`);
137
+ }
138
+ }
139
+ }
140
+
141
+ function formatMs(v) {
142
+ if (v === undefined || v === null) {
143
+ return '-';
144
+ }
145
+ if (v >= 1000) {
146
+ return (v / 1000).toFixed(1) + ' s';
147
+ }
148
+ return v.toFixed(0) + ' ms';
149
+ }
150
+
151
+ function printTable(headers, rows) {
152
+ const widths = headers.map((h, i) => {
153
+ let w = h.length;
154
+ for (const r of rows) {
155
+ if (r[i] && r[i].length > w) {
156
+ w = r[i].length;
157
+ }
158
+ }
159
+ return w;
160
+ });
161
+ const align = (cell, i) => {
162
+ if (i === 0) {
163
+ return cell.padEnd(widths[i]);
164
+ }
165
+ return cell.padStart(widths[i]);
166
+ };
167
+ console.log(' ' + headers.map((h, i) => align(h, i)).join(' '));
168
+ for (const r of rows) {
169
+ console.log(' ' + r.map((c, i) => align(c, i)).join(' '));
170
+ }
171
+ }