exifreader 4.34.0 → 4.36.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.
package/README.md CHANGED
@@ -315,6 +315,91 @@ const tags = ExifReader.load(fileBuffer, {includeUnknown: true});
315
315
  If you discover an unknown tag that should be handled by ExifReader, please
316
316
  reach out by filing an issue.
317
317
 
318
+ #### Filtering tags (includeTags / excludeTags)
319
+
320
+ You can filter which tags are returned by using `includeTags` and/or
321
+ `excludeTags`.
322
+
323
+ - If `includeTags` is provided, it uses an **include-pattern**: only the groups
324
+ you specify will be included in the output.
325
+ - `excludeTags` can be used alone to remove tags/groups while keeping everything
326
+ else.
327
+ - If a group is specified in both `includeTags` and `excludeTags`, `excludeTags`
328
+ for that group will be ignored.
329
+ - An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
330
+ excluding that group. The group will not be returned and ExifReader will skip
331
+ parsing it.
332
+
333
+ **Examples**
334
+
335
+ Exclude a few tags in the Exif group:
336
+
337
+ ```javascript
338
+ const tags = ExifReader.load(fileBuffer, {
339
+ excludeTags: {
340
+ exif: ['MakerNote', 0x9286],
341
+ }
342
+ });
343
+ ```
344
+
345
+ Only return XMP tags (and exclude everything else):
346
+
347
+ ```javascript
348
+ const tags = ExifReader.load(fileBuffer, {
349
+ includeTags: {
350
+ xmp: true,
351
+ }
352
+ });
353
+ ```
354
+
355
+ **Filtering groups**
356
+
357
+ The group keys follow the same concept as the output when `expanded: true` is
358
+ used. (The `thumbnail` group controls the top-level `Thumbnail` value.)
359
+
360
+ For PNG, filtering is done with the `png` group only. (The `pngFile` and
361
+ `pngText` groups exist in `expanded` output today, but `png` is the filtering key
362
+ and those groups will be deprecated later.)
363
+
364
+ | Group key | Description | Supports IDs |
365
+ | ------------- | ------------------------------------------------ | ------------ |
366
+ | `exif` | Exif tags (including GPS IFD, interoperability). | yes |
367
+ | `iptc` | IPTC tags. | yes |
368
+ | `xmp` | XMP tags. | no |
369
+ | `icc` | ICC profile tags. | no |
370
+ | `photoshop` | Photoshop resource tags. | yes |
371
+ | `makerNotes` | MakerNote tags (e.g. Canon/Pentax). | yes |
372
+ | `mpf` | MPF tags. | yes |
373
+ | `file` | JPEG file details and `FileType`. | no |
374
+ | `jfif` | JFIF tags. | no |
375
+ | `png` | PNG header, chunk, and text tags. | no |
376
+ | `riff` | WebP (RIFF) tags. | no |
377
+ | `gif` | GIF tags. | no |
378
+ | `gps` | Computed GPS group (only when `expanded: true`). | no |
379
+ | `composite` | Composite tags (e.g. FieldOfView). | no |
380
+ | `thumbnail` | Top-level `Thumbnail` output. | no |
381
+
382
+ **Important: dependency tags**
383
+
384
+ Some tags act as pointers or containers to other metadata. Excluding them can
385
+ cause other tags or entire groups to disappear. Some important examples:
386
+
387
+ - `Exif IFD Pointer`, `GPS Info IFD Pointer`, `Interoperability IFD Pointer`
388
+ - `IPTC-NAA` (TIFF embedded IPTC), `ApplicationNotes` (TIFF embedded XMP),
389
+ `ICC_Profile` (TIFF embedded ICC)
390
+ - `MakerNote` and `Make` (maker note parsing)
391
+ - `ImageSourceData` and `PhotoshopSettings` (Photoshop parsing)
392
+ - `JPEGInterchangeFormat` and `JPEGInterchangeFormatLength` (thumbnails)
393
+
394
+ **NOTE:** When using `includeTags`, you **do not** have to list these dependency
395
+ tags. ExifReader will automatically include the required pointer/container tags
396
+ needed to find and parse the groups you requested. This section mainly matters
397
+ when using `excludeTags`.
398
+
399
+ Note that XMP and ICC tags are parsed from full metadata blocks, so ExifReader
400
+ cannot skip parsing individual XMP/ICC tags based on selectors. The returned
401
+ output is still filtered.
402
+
318
403
  #### Computed tag values (opt-in)
319
404
 
320
405
  ExifReader exposes three different values per Exif tag:
@@ -623,6 +708,9 @@ Changelog
623
708
 
624
709
  A selection of notable changes.
625
710
 
711
+ - **January 2026**:
712
+ - Add `includeTags` / `excludeTags` options for filtering returned tags by
713
+ group and tag name/ID.
626
714
  - **December 2025**:
627
715
  - Add the `computed` tag property that are a middle way between the raw
628
716
  `value` and the human-friendly `description`.