exifreader 4.53.0 → 4.55.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 +404 -33
- package/bin/analyze.js +139 -9
- package/bin/build-pages.js +21 -35
- package/bin/cli.js +81 -13
- package/bin/generate-tag-modules.js +287 -0
- package/dist/exif-reader.js +1 -1
- package/dist/exif-reader.js.map +1 -1
- package/exif-reader.d.ts +213 -38
- package/package.json +71 -11
- package/src/base64-image.js +27 -0
- package/src/composable/brand.js +10 -0
- package/src/composable/composition-tag-filter.js +97 -0
- package/src/composable/composition.js +195 -0
- package/src/composable/core.d.ts +148 -0
- package/src/composable/core.js +526 -0
- package/src/composable/exif-block-reader.js +197 -0
- package/src/composable/formats/avif.js +19 -0
- package/src/composable/formats/gif.js +28 -0
- package/src/composable/formats/heic.js +19 -0
- package/src/composable/formats/iso-bmff-file-reader.js +14 -0
- package/src/composable/formats/jpeg.js +55 -0
- package/src/composable/formats/jxl.js +30 -0
- package/src/composable/formats/png.js +187 -0
- package/src/composable/formats/tiff.js +18 -0
- package/src/composable/formats/webp.js +28 -0
- package/src/composable/formats/xml.js +18 -0
- package/src/composable/formats.d.ts +17 -0
- package/src/composable/formats.js +17 -0
- package/src/composable/group-helpers.js +129 -0
- package/src/composable/groups/canon.js +26 -0
- package/src/composable/groups/composite.js +43 -0
- package/src/composable/groups/exif.js +48 -0
- package/src/composable/groups/gps.js +75 -0
- package/src/composable/groups/icc.js +52 -0
- package/src/composable/groups/iptc.js +86 -0
- package/src/composable/groups/maker-notes.js +21 -0
- package/src/composable/groups/mpf.js +25 -0
- package/src/composable/groups/pentax.js +34 -0
- package/src/composable/groups/photoshop.js +18 -0
- package/src/composable/groups/thumbnail.js +131 -0
- package/src/composable/groups/xmp.js +118 -0
- package/src/composable/groups.d.ts +20 -0
- package/src/composable/groups.js +105 -0
- package/src/composable/iptc-block-reader.js +44 -0
- package/src/composable/read-view.js +165 -0
- package/src/composable/tag-binding-name.js +17 -0
- package/src/composable/tags/exif.d.ts +295 -0
- package/src/composable/tags/exif.js +396 -0
- package/src/composable/tags/iptc.d.ts +84 -0
- package/src/composable/tags/iptc.js +109 -0
- package/src/composable/value-budget.js +24 -0
- package/src/composite.js +2 -2
- package/src/decompression.js +60 -0
- package/src/dom-parser.js +5 -6
- package/src/engine.js +332 -0
- package/src/errors.js +8 -2
- package/src/exif-reader.d.ts +8 -0
- package/src/exif-reader.js +118 -1121
- package/src/file-loaders.js +74 -1
- package/src/file-tags.js +9 -9
- package/src/image-header-avif.js +7 -8
- package/src/image-header-gif.js +9 -10
- package/src/image-header-heic.js +7 -8
- package/src/image-header-iso-bmff.js +71 -92
- package/src/image-header-jpeg.js +60 -59
- package/src/image-header-jxl.js +59 -65
- package/src/image-header-png.js +199 -76
- package/src/image-header-tiff.js +7 -4
- package/src/image-header-webp.js +29 -35
- package/src/image-header.js +25 -59
- package/src/iptc-tag-names-descriptions.js +334 -0
- package/src/iptc-tag-names.js +50 -306
- package/src/iptc-tags.js +41 -27
- package/src/jfif-tags.js +9 -9
- package/src/load-auto.js +2 -2
- package/src/loadview-pipeline.js +197 -498
- package/src/mpf-tags.js +10 -7
- package/src/node-require.js +15 -2
- package/src/png-text-tags.js +90 -327
- package/src/tag-filter-config.js +24 -15
- package/src/tag-filter.js +67 -3
- package/src/tag-names-0th-ifd-descriptions.js +232 -0
- package/src/tag-names-0th-ifd.js +49 -173
- package/src/tag-names-common.js +263 -211
- package/src/tag-names-exif-ifd-descriptions.js +249 -0
- package/src/tag-names-exif-ifd.js +55 -187
- package/src/tag-names-gps-ifd-descriptions.js +156 -0
- package/src/tag-names-gps-ifd.js +39 -146
- package/src/tag-names-utils.js +33 -10
- package/src/tags-helpers.js +14 -24
- package/src/tags.js +23 -11
- package/src/thumbnail.js +7 -5
- package/src/types.js +2 -0
- package/src/unsupported-format-error.js +21 -0
- package/src/utils.js +64 -119
- package/src/writer/exif-tag-table.js +321 -0
- package/src/xml.js +12 -15
- package/src/xmp-tag-names.js +42 -21
- package/src/xmp-tags.js +9 -10
- package/webpack.config.js +1 -1
package/README.md
CHANGED
|
@@ -11,9 +11,10 @@ If you use the `length: 'auto'` option, ExifReader reads only the bytes
|
|
|
11
11
|
that contain metadata, **well under 1 ms per file** for typical phone JPEGs
|
|
12
12
|
and **over 95% less bandwidth**.
|
|
13
13
|
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
14
|
+
You can compose a reader from only the formats, groups and tags you read. A
|
|
15
|
+
reader of the date and the GPS position of JPEG files bundles to
|
|
16
|
+
**about 12 KiB** (esbuild, minified, Brotli). See [the composable
|
|
17
|
+
API](#composable-api).
|
|
17
18
|
|
|
18
19
|
ExifReader supports module formats ESM, AMD, CommonJS, and globals and can
|
|
19
20
|
therefore easily be used from Webpack, RequireJS, Browserify, Node etc.
|
|
@@ -65,7 +66,9 @@ Table of Contents
|
|
|
65
66
|
1. [Support](#support)
|
|
66
67
|
2. [Installation](#installation)
|
|
67
68
|
3. [Usage](#usage)
|
|
68
|
-
|
|
69
|
+
- [Composable API](#composable-api)
|
|
70
|
+
- [Migrating to the composable API](#migrating-to-the-composable-api)
|
|
71
|
+
4. [Configure a Custom Build (deprecated)](#configure-a-custom-build)
|
|
69
72
|
5. [Notes](#notes)
|
|
70
73
|
6. [Client/Browser Support](#clientbrowser-support)
|
|
71
74
|
7. [Examples](#examples)
|
|
@@ -114,7 +117,15 @@ After that, the transpiled, concatenated and minified ES5 file will be in the
|
|
|
114
117
|
|
|
115
118
|
### Type definitions
|
|
116
119
|
|
|
117
|
-
Type definitions for TypeScript are included in the package.
|
|
120
|
+
Type definitions for TypeScript are included in the package. Each subpath of
|
|
121
|
+
the [composable API](#composable-api) (`exifreader/core`, `exifreader/formats`,
|
|
122
|
+
`exifreader/groups`, `exifreader/tags/exif` and `exifreader/tags/iptc`) ships
|
|
123
|
+
its own definitions next to its module, which TypeScript finds with
|
|
124
|
+
`moduleResolution` set to `bundler`, `node16` or `nodenext`. A CommonJS file
|
|
125
|
+
can import them only with `module` set to `nodenext` or `node20` (see
|
|
126
|
+
Toolchains in [the composable API](#composable-api)). `exifreader/core` also
|
|
127
|
+
exports the types of the arguments to `load`, `LoadInput` and `LoadOptions`, and
|
|
128
|
+
of its result, `Tags` and `ExpandedTags`.
|
|
118
129
|
|
|
119
130
|
Usage
|
|
120
131
|
-----
|
|
@@ -156,6 +167,24 @@ requirejs(['/path/to/exif-reader.js'], function (ExifReader) {
|
|
|
156
167
|
<script src="/path/to/exif-reader.js"></script>
|
|
157
168
|
```
|
|
158
169
|
|
|
170
|
+
> **In a browser app?** If you only need a few tags, compose a reader with only
|
|
171
|
+
> what you read. This one reads the date and the GPS position of JPEG files:
|
|
172
|
+
>
|
|
173
|
+
> ```javascript
|
|
174
|
+
> import {createReader} from 'exifreader/core';
|
|
175
|
+
> import {jpeg} from 'exifreader/formats';
|
|
176
|
+
> import {gps} from 'exifreader/groups';
|
|
177
|
+
> import {DateTimeOriginal} from 'exifreader/tags/exif';
|
|
178
|
+
>
|
|
179
|
+
> const reader = createReader({formats: [jpeg], groups: [gps], tags: [DateTimeOriginal]});
|
|
180
|
+
> const tags = await reader.load(file);
|
|
181
|
+
> // tags.exif.DateTimeOriginal, tags.gps.Latitude, tags.gps.Longitude
|
|
182
|
+
> ```
|
|
183
|
+
>
|
|
184
|
+
> It bundles to about 12 KiB, against about 42 KiB for the default entry
|
|
185
|
+
> (esbuild, minified, Brotli). See [the composable API](#composable-api) for the
|
|
186
|
+
> rest. For everything else, start with the default entry as shown above.
|
|
187
|
+
|
|
159
188
|
### Loading tags
|
|
160
189
|
|
|
161
190
|
There are two ways to load the tags. Either have ExifReader do the loading of
|
|
@@ -255,6 +284,9 @@ You can filter which tags are returned by using `includeTags` and/or
|
|
|
255
284
|
- An empty selector array (e.g. `includeTags: { xmp: [] }`) is treated as
|
|
256
285
|
excluding that group. The group will not be returned and ExifReader will skip
|
|
257
286
|
parsing it.
|
|
287
|
+
- A group's value can be `true`, an array of selectors, or `false` to leave the
|
|
288
|
+
group out. That is useful with a boolean variable, e.g.
|
|
289
|
+
`includeTags: { exif: true, xmp: includeXmp }`.
|
|
258
290
|
|
|
259
291
|
**Examples**
|
|
260
292
|
|
|
@@ -281,7 +313,7 @@ const tags = ExifReader.load(fileBuffer, {
|
|
|
281
313
|
**Filtering groups**
|
|
282
314
|
|
|
283
315
|
The group keys follow the same concept as the output when `expanded: true` is
|
|
284
|
-
used. (The `thumbnail` group controls the top-level `
|
|
316
|
+
used. (The `thumbnail` group controls the top-level `thumbnail` value.)
|
|
285
317
|
|
|
286
318
|
For PNG, filtering is done with the `png` group only. (The `pngFile` and
|
|
287
319
|
`pngText` groups exist in `expanded` output today, but `png` is the filtering
|
|
@@ -303,7 +335,7 @@ key and those groups will be deprecated later.)
|
|
|
303
335
|
| `gif` | GIF tags. | no |
|
|
304
336
|
| `gps` | Computed GPS group (only when `expanded: true`). | no |
|
|
305
337
|
| `composite` | Composite tags (e.g. FieldOfView). | no |
|
|
306
|
-
| `thumbnail` | Top-level `
|
|
338
|
+
| `thumbnail` | Top-level `thumbnail` output. | no |
|
|
307
339
|
|
|
308
340
|
**Important: dependency tags**
|
|
309
341
|
|
|
@@ -329,7 +361,7 @@ output is still filtered.
|
|
|
329
361
|
Filtering removes parsed tags only, not the raw data they were parsed from.
|
|
330
362
|
Some tags hold such data, for example `xmp._raw` (with `expanded: true`), the
|
|
331
363
|
Exif `ApplicationNotes` and `IPTC-NAA` tags, the MPF `Images`, PNG text tags
|
|
332
|
-
and `
|
|
364
|
+
and `thumbnail`. When filtering for privacy, list the tags you want in
|
|
333
365
|
`includeTags` (by name, not `true`) instead of excluding the ones you do not.
|
|
334
366
|
|
|
335
367
|
#### Unknown tags
|
|
@@ -712,6 +744,9 @@ API](https://developer.mozilla.org/en-US/docs/Web/API/DOMParser/parseFromString)
|
|
|
712
744
|
Use [`xmldom`](https://www.npmjs.com/package/@xmldom/xmldom) 0.9.12 or later.
|
|
713
745
|
ExifReader limits how deeply XMP elements can nest and how many markup nodes a
|
|
714
746
|
packet can have, and it checks those limits the way `xmldom` reads markup.
|
|
747
|
+
Older versions of `xmldom` read some markup differently, well-formed markup
|
|
748
|
+
included, so with them a crafted file can get past the limits and make parsing
|
|
749
|
+
slow.
|
|
715
750
|
|
|
716
751
|
[`linkedom`](https://www.npmjs.com/package/linkedom) also parses XMP correctly,
|
|
717
752
|
but use it only for files you trust. ExifReader's limits do not hold with it: a
|
|
@@ -734,12 +769,9 @@ these XMLs. If this happens to you, switch to `xmldom` and pass in the `onError`
|
|
|
734
769
|
option. (NOTE: The native `DOMParser` that a web browser uses does not seem to
|
|
735
770
|
have this issue.)
|
|
736
771
|
|
|
737
|
-
|
|
738
|
-
|
|
739
|
-
|
|
740
|
-
DOCTYPE or another markup declaration, since a parser such as a browser's
|
|
741
|
-
native `DOMParser` can expand the entities declared in a DOCTYPE into markup
|
|
742
|
-
the limits do not see.
|
|
772
|
+
ExifReader skips an XMP packet that has a DOCTYPE or another markup
|
|
773
|
+
declaration, since a parser such as a browser's native `DOMParser` can expand
|
|
774
|
+
the entities declared in a DOCTYPE into markup the limits do not see.
|
|
743
775
|
|
|
744
776
|
If you pass no `domParser` and there is no global `DOMParser`, ExifReader tries
|
|
745
777
|
to load `@xmldom/xmldom` itself. It then skips XMP, with a warning, if the copy
|
|
@@ -752,7 +784,22 @@ npm override, a Yarn resolution or a pnpm override pins `@xmldom/xmldom` below
|
|
|
752
784
|
|
|
753
785
|
#### Using React Native
|
|
754
786
|
|
|
755
|
-
|
|
787
|
+
React Native 0.79 and later (Metro 0.82 and later) resolve the subpaths of the
|
|
788
|
+
[composable API](#composable-api), so you can import `exifreader/core` and the
|
|
789
|
+
other subpaths directly and pass the same buffer as below to
|
|
790
|
+
`await reader.load(fileBuffer)`. React Native has no `DOMParser`, so a reader
|
|
791
|
+
with `xmp` needs a parser passed to `createReader` in its `domParser` key (see
|
|
792
|
+
[Parsing XMP tags when not in a DOM
|
|
793
|
+
environment](#parsing-xmp-tags-when-not-in-a-dom-environment)).
|
|
794
|
+
|
|
795
|
+
Metro does not tree shake, so it loads every format and group the imported
|
|
796
|
+
subpaths reference. Under Metro 0.88, a reader of JPEG files with `gps` and two
|
|
797
|
+
tags is over 230 KiB raw and 60 KiB gzip. That is still smaller than the
|
|
798
|
+
default entry under Metro (over 250 KiB and 75 KiB), but esbuild bundles the
|
|
799
|
+
one-tag `Single tags` example of the [composable API](#composable-api) to about
|
|
800
|
+
39 KiB and 13 KiB.
|
|
801
|
+
|
|
802
|
+
With the default entry, or an older Metro, import ExifReader like this:
|
|
756
803
|
|
|
757
804
|
```javascript
|
|
758
805
|
import ExifReader from './node_modules/exifreader/src/exif-reader.js';
|
|
@@ -793,18 +840,18 @@ values](https://github.com/mattiasw/ExifReader/issues/378#issuecomment-230270598
|
|
|
793
840
|
|
|
794
841
|
### Using the thumbnail
|
|
795
842
|
|
|
796
|
-
The thumbnail and its details will be accessible through `tags['
|
|
843
|
+
The thumbnail and its details will be accessible through `tags['thumbnail']`.
|
|
797
844
|
There is information about e.g. width and height, and the thumbnail image data
|
|
798
|
-
is stored in `tags['
|
|
845
|
+
is stored in `tags['thumbnail'].image`.
|
|
799
846
|
|
|
800
847
|
How you use it is going to depend on your environment. For a web browser you can
|
|
801
|
-
either use the raw byte data in `tags['
|
|
802
|
-
want, or you can use the helper property `tags['
|
|
848
|
+
either use the raw byte data in `tags['thumbnail'].image` and use it the way you
|
|
849
|
+
want, or you can use the helper property `tags['thumbnail'].base64` that is a
|
|
803
850
|
base64 representation of the image. It can be used for a data URI like this:
|
|
804
851
|
|
|
805
852
|
```javascript
|
|
806
853
|
const tags = ExifReader.load(fileBuffer);
|
|
807
|
-
imageElement.src = 'data:image/jpg;base64,' + tags['
|
|
854
|
+
imageElement.src = 'data:image/jpg;base64,' + tags['thumbnail'].base64;
|
|
808
855
|
```
|
|
809
856
|
|
|
810
857
|
If you're using node, you can store it as a new file like this:
|
|
@@ -812,19 +859,317 @@ If you're using node, you can store it as a new file like this:
|
|
|
812
859
|
```javascript
|
|
813
860
|
const fs = require('fs');
|
|
814
861
|
const tags = ExifReader.load(fileBuffer);
|
|
815
|
-
fs.writeFileSync('/path/to/new/thumbnail.jpg', Buffer.from(tags['
|
|
862
|
+
fs.writeFileSync('/path/to/new/thumbnail.jpg', Buffer.from(tags['thumbnail'].image));
|
|
816
863
|
```
|
|
817
864
|
|
|
865
|
+
On `ExifReader.load` and `loadView`, `tags['Thumbnail']` is the old name of the
|
|
866
|
+
same value and is removed in v5. Until then it is the one that `Object.keys` and
|
|
867
|
+
`JSON.stringify` list, since `thumbnail` is not enumerable there, so a copy of
|
|
868
|
+
the result (spread, `Object.assign`, `structuredClone` or a JSON round trip)
|
|
869
|
+
keeps only `Thumbnail`. When a file has a PNG text or XMP tag named
|
|
870
|
+
`thumbnail`, that tag keeps the key in the flat result, so code that has to
|
|
871
|
+
handle such files reads `Thumbnail` until v5. A reader from the
|
|
872
|
+
[composable API](#composable-api) returns only `thumbnail`.
|
|
873
|
+
|
|
818
874
|
See the [examples site](https://mattiasw.github.io/ExifReader/) for more
|
|
819
875
|
details.
|
|
820
876
|
|
|
821
877
|
### Optimizing build size
|
|
822
878
|
|
|
823
|
-
|
|
824
|
-
|
|
879
|
+
#### Composable API
|
|
880
|
+
|
|
881
|
+
Import only the formats, groups and tags you read, and your bundler leaves out
|
|
882
|
+
the rest.
|
|
883
|
+
|
|
884
|
+
**Whole groups.** This reader reads the Exif and XMP tags of JPEG and HEIC
|
|
885
|
+
files:
|
|
825
886
|
|
|
826
|
-
|
|
827
|
-
|
|
887
|
+
```javascript
|
|
888
|
+
import {createReader} from 'exifreader/core';
|
|
889
|
+
import {jpeg, heic} from 'exifreader/formats';
|
|
890
|
+
import {exif, xmp} from 'exifreader/groups';
|
|
891
|
+
|
|
892
|
+
const reader = createReader({formats: [jpeg, heic], groups: [exif, xmp]});
|
|
893
|
+
const tags = await reader.load(file);
|
|
894
|
+
```
|
|
895
|
+
|
|
896
|
+
**Single tags.** This one reads only the date and the GPS position of JPEG
|
|
897
|
+
files:
|
|
898
|
+
|
|
899
|
+
```javascript
|
|
900
|
+
import {createReader} from 'exifreader/core';
|
|
901
|
+
import {jpeg} from 'exifreader/formats';
|
|
902
|
+
import {gps} from 'exifreader/groups';
|
|
903
|
+
import {DateTimeOriginal} from 'exifreader/tags/exif';
|
|
904
|
+
|
|
905
|
+
const reader = createReader({formats: [jpeg], groups: [gps], tags: [DateTimeOriginal]});
|
|
906
|
+
const tags = await reader.load(file);
|
|
907
|
+
// tags.exif.DateTimeOriginal, tags.gps.Latitude, tags.gps.Longitude
|
|
908
|
+
```
|
|
909
|
+
|
|
910
|
+
The output is grouped, since a reader is built from groups. `expanded: false`
|
|
911
|
+
gives flat output, for code that moves over from `ExifReader.load` (see
|
|
912
|
+
[Migrating to the composable API](#migrating-to-the-composable-api) for what
|
|
913
|
+
differs). In flat output the name `thumbnail` is reserved for the
|
|
914
|
+
thumbnail, so a PNG text or XMP tag of that name is read from the grouped
|
|
915
|
+
output (`tags.png.thumbnail`, `tags.xmp.thumbnail`). `tags.gps` (`Latitude`,
|
|
916
|
+
`Longitude` and `Altitude`) is only in the grouped output. In a flat load, `gps`
|
|
917
|
+
therefore adds no GPS values at all: a reader composed with `gps` alone returns
|
|
918
|
+
only the `file` and `jfif` tags for a JPEG file. For GPS values in flat output,
|
|
919
|
+
import `GPSLatitude`, `GPSLatitudeRef`, `GPSLongitude`, `GPSLongitudeRef`,
|
|
920
|
+
`GPSAltitude` and `GPSAltitudeRef` from `exifreader/tags/exif` and pass them in
|
|
921
|
+
`tags`. A flat load then has `GPSLatitude` with its unsigned decimal
|
|
922
|
+
description, and the `Ref` tags carry the hemisphere and whether the altitude is
|
|
923
|
+
below sea level (see [Notes](#notes) and the [GPS section](#gps)).
|
|
924
|
+
|
|
925
|
+
A group or tag the file does not hold is absent from the result, so
|
|
926
|
+
`tags.exif?.DateTimeOriginal?.description` covers every case.
|
|
927
|
+
|
|
928
|
+
**What a group brings.** Each group reads the Exif tags it needs: `gps` the six
|
|
929
|
+
GPS tags its values come from, `xmp` `ApplicationNotes`, `iptc` `IPTC-NAA`,
|
|
930
|
+
`icc` `ICC_Profile`, `photoshop` `ImageSourceData` and `PhotoshopSettings`,
|
|
931
|
+
`makerNotes`, `canon` and `pentax` `MakerNote` and `Make`, `thumbnail`
|
|
932
|
+
`JPEGInterchangeFormat` and `JPEGInterchangeFormatLength`, and `composite` the
|
|
933
|
+
focal length and pixel dimension tags it computes its values from. The reader
|
|
934
|
+
reads those tags but returns them only when they are also in `tags` or the
|
|
935
|
+
whole `exif` group is composed: with `makerNotes`, for example, add `Make` to
|
|
936
|
+
`tags` to get `exif.Make`. A format brings its own tags: every format gives
|
|
937
|
+
`file` (`FileType`, and the image details where the format has them), and
|
|
938
|
+
`jpeg` adds `jfif`, `png` adds `png`, `webp` adds `riff` and `gif` adds `gif`.
|
|
939
|
+
The grouped output of a composed reader has `png` alone, which holds every tag
|
|
940
|
+
of `pngFile` and `pngText`, not those two groups.
|
|
941
|
+
|
|
942
|
+
**Tags.** `tags` takes Exif and IPTC tags, imported from `exifreader/tags/exif`
|
|
943
|
+
and `exifreader/tags/iptc`. With `iptc` not in `groups`, a reader composed with
|
|
944
|
+
IPTC tags returns only those, and it reads the block's `Coded Character Set`
|
|
945
|
+
for the text encoding even when that tag is not in `tags`. MPF tags come only
|
|
946
|
+
with the whole `mpf` group. Three IPTC tags come only with the whole `iptc`
|
|
947
|
+
group: `ObjectData Preview File Format` and `Record 2 destination` (dataset
|
|
948
|
+
2:200), whose name depends on the length of the value, so no import can select
|
|
949
|
+
it, and `ObjectData Preview File Format Version` (2:201), whose description is
|
|
950
|
+
read from dataset 2:200. A tag's import name differs from its key in the result
|
|
951
|
+
when its name has characters a JavaScript name cannot hold, so `ByLine` is read
|
|
952
|
+
as `tags.iptc['By-line']` and `SubLocation` as `tags.iptc['Sub-location']`.
|
|
953
|
+
The keys in the result are the same as in `ExifReader.load`.
|
|
954
|
+
On a composed reader, a repeatable IPTC dataset such as `Keywords` is always an
|
|
955
|
+
array of tag objects, also when the file holds it once. In the flat output an
|
|
956
|
+
XMP tag of the same name replaces it, as it does in `ExifReader.load`.
|
|
957
|
+
|
|
958
|
+
**Subpaths.**
|
|
959
|
+
|
|
960
|
+
| Subpath | Exports |
|
|
961
|
+
|---|---|
|
|
962
|
+
| `exifreader/core` | `createReader`, `errors` (`UnsupportedFormatError`), `tagFilter` |
|
|
963
|
+
| `exifreader/formats` | `tiff`, `jpeg`, `png`, `heic`, `avif`, `jxl`, `webp`, `gif`, `xml` (XMP sidecar files; returns only `FileType` without `xmp` in `groups`), `allFormats` |
|
|
964
|
+
| `exifreader/groups` | `exif`, `iptc`, `xmp`, `icc`, `photoshop`, `mpf`, `makerNotes`, `canon`, `pentax`, `gps`, `composite`, `thumbnail`, `allGroups` |
|
|
965
|
+
| `exifreader/tags/exif`, `exifreader/tags/iptc` | One export per tag, named after the tag with every character that cannot be in a JavaScript name removed and the letter after it upper-cased (`By-line` becomes `ByLine`, `GPS Info IFD Pointer` becomes `GPSInfoIFDPointer`) |
|
|
966
|
+
|
|
967
|
+
`makerNotes` holds every maker note decoder and grows with new releases.
|
|
968
|
+
`canon` and `pentax` hold one each.
|
|
969
|
+
|
|
970
|
+
Pass these values as they are imported. A copy or an altered copy of a format,
|
|
971
|
+
group or tag is not supported.
|
|
972
|
+
|
|
973
|
+
**Everything.** `createReader({formats: allFormats, groups: allGroups})` reads
|
|
974
|
+
everything (`allGroups` has `makerNotes`, not `canon` or `pentax`). Filtering
|
|
975
|
+
these arrays skips parsing but does not shrink the bundle, since the bundler
|
|
976
|
+
cannot see which entries you keep. Import by name instead. Composing `heic`
|
|
977
|
+
without `avif` saves little (under 0.1 KiB).
|
|
978
|
+
|
|
979
|
+
**Loading.** `reader.load` takes the image bytes or a `Blob` or `File`:
|
|
980
|
+
|
|
981
|
+
| You have | Call |
|
|
982
|
+
|---|---|
|
|
983
|
+
| A `File` from `<input type="file">` | `reader.load(file)`; for the first n bytes, `reader.load(file.slice(0, n))` |
|
|
984
|
+
| A path in Node | `reader.load(await readFile(path))` (`readFile` from `node:fs/promises`) |
|
|
985
|
+
| A path in Node, the first n bytes only | `reader.load((await openAsBlob(path)).slice(0, n))` (`openAsBlob` from `node:fs`) |
|
|
986
|
+
| A path in Bun | `reader.load(Bun.file(path))` |
|
|
987
|
+
| A URL | `reader.load(await (await fetch(url)).arrayBuffer())` |
|
|
988
|
+
| A `Response` | `reader.load(await response.arrayBuffer())` |
|
|
989
|
+
| A `ReadableStream` | `reader.load(await new Response(stream).arrayBuffer())` |
|
|
990
|
+
| Bytes: an `ArrayBuffer`, `SharedArrayBuffer`, `DataView`, typed array such as `Uint8Array`, or Node `Buffer` | `reader.load(bytes)` |
|
|
991
|
+
|
|
992
|
+
`reader.load` always returns a Promise and never throws: every failure is a
|
|
993
|
+
rejection. It does not take strings or URLs, and it has no `length` or `async`
|
|
994
|
+
option (both reject). Passing `domParser` or `decompress` to `reader.load`
|
|
995
|
+
rejects too, as both go to `createReader`. The options it takes are `expanded`,
|
|
996
|
+
`includeUnknown`, `computed`, `includeOffsets`, `includeTags` and `excludeTags`;
|
|
997
|
+
the first four take only `true`, `false` or `undefined`, and any other value
|
|
998
|
+
rejects.
|
|
999
|
+
`expanded: false` gives the flat output, and `includeOffsets` needs no
|
|
1000
|
+
`expanded` (it does nothing with `expanded: false`).
|
|
1001
|
+
|
|
1002
|
+
**Errors.** Input that no composed format recognizes rejects with
|
|
1003
|
+
`UnsupportedFormatError`, so a reader of JPEG files only rejects a PNG file
|
|
1004
|
+
that way. The message names the formats of the reader in detection order: the
|
|
1005
|
+
JPEG-only reader below rejects with `reader.load: none of this reader's formats
|
|
1006
|
+
(jpeg) recognizes the input: it is in another format or is not an image`. Check
|
|
1007
|
+
for it with `error instanceof errors.UnsupportedFormatError`,
|
|
1008
|
+
using the `errors` of the entry the reader came from (`exifreader/core` for
|
|
1009
|
+
`createReader`, `ExifReader.errors` for the default entry, which under Node is
|
|
1010
|
+
the bundled `dist` file with its own copy of the class), or with
|
|
1011
|
+
`error.name === 'UnsupportedFormatError'`:
|
|
1012
|
+
|
|
1013
|
+
```javascript
|
|
1014
|
+
import {createReader, errors} from 'exifreader/core';
|
|
1015
|
+
import {jpeg} from 'exifreader/formats';
|
|
1016
|
+
import {exif} from 'exifreader/groups';
|
|
1017
|
+
|
|
1018
|
+
const reader = createReader({formats: [jpeg], groups: [exif]});
|
|
1019
|
+
try {
|
|
1020
|
+
const tags = await reader.load(file);
|
|
1021
|
+
} catch (error) {
|
|
1022
|
+
if (error instanceof errors.UnsupportedFormatError) {
|
|
1023
|
+
// Not a JPEG file.
|
|
1024
|
+
}
|
|
1025
|
+
}
|
|
1026
|
+
```
|
|
1027
|
+
|
|
1028
|
+
**XMP outside browsers.** Node, Bun, Deno, web workers and React Native have no
|
|
1029
|
+
`DOMParser`. With `xmp` composed, pass one to `createReader` in its `domParser`
|
|
1030
|
+
key (see [Parsing XMP tags when not in a DOM
|
|
1031
|
+
environment](#parsing-xmp-tags-when-not-in-a-dom-environment)):
|
|
1032
|
+
|
|
1033
|
+
```javascript
|
|
1034
|
+
import {createReader} from 'exifreader/core';
|
|
1035
|
+
import {jpeg} from 'exifreader/formats';
|
|
1036
|
+
import {xmp} from 'exifreader/groups';
|
|
1037
|
+
import {DOMParser, onErrorStopParsing} from '@xmldom/xmldom';
|
|
1038
|
+
|
|
1039
|
+
const reader = createReader({formats: [jpeg], groups: [xmp], domParser: new DOMParser({onError: onErrorStopParsing})});
|
|
1040
|
+
const tags = await reader.load(data);
|
|
1041
|
+
```
|
|
1042
|
+
|
|
1043
|
+
Without one, `reader.load` rejects with a message naming `domParser`. The check
|
|
1044
|
+
runs at load, so creating the reader where there is no `DOMParser`, such as
|
|
1045
|
+
during server rendering, does not throw. A composed reader never loads
|
|
1046
|
+
`@xmldom/xmldom` by itself.
|
|
1047
|
+
|
|
1048
|
+
**Decompression.** Custom Brotli or deflate functions and `maxDecompressedSize`
|
|
1049
|
+
go to `createReader` in its `decompress` key, the object that [Custom
|
|
1050
|
+
decompression](#custom-decompression) and [Limiting decompressed metadata
|
|
1051
|
+
size](#limiting-decompressed-metadata-size) describe for `ExifReader.load`. The
|
|
1052
|
+
limit applies to each `reader.load` call on its own:
|
|
1053
|
+
|
|
1054
|
+
```javascript
|
|
1055
|
+
import zlib from 'node:zlib';
|
|
1056
|
+
import {createReader} from 'exifreader/core';
|
|
1057
|
+
import {jxl} from 'exifreader/formats';
|
|
1058
|
+
import {exif} from 'exifreader/groups';
|
|
1059
|
+
|
|
1060
|
+
const reader = createReader({
|
|
1061
|
+
formats: [jxl],
|
|
1062
|
+
groups: [exif],
|
|
1063
|
+
decompress: {
|
|
1064
|
+
brotli: (data, {maxOutputLength}) => zlib.brotliDecompressSync(data, {maxOutputLength}),
|
|
1065
|
+
maxDecompressedSize: 16 * 1024 * 1024
|
|
1066
|
+
}
|
|
1067
|
+
});
|
|
1068
|
+
```
|
|
1069
|
+
|
|
1070
|
+
**Filtering.** `includeTags` and `excludeTags` need `tagFilter`, imported from
|
|
1071
|
+
`exifreader/core`, in `createReader`. Without it, `reader.load` rejects with a
|
|
1072
|
+
message naming the option. With it, `reader.load` also rejects an option that
|
|
1073
|
+
is not an object keyed by group, a key that is not a group (a misspelt one such
|
|
1074
|
+
as `exiff`), and a group value other than `true`, `false` or an array of tag
|
|
1075
|
+
names or ids. A group the reader does not compose is not an error: it is absent
|
|
1076
|
+
from the result. The options narrow what the reader composes and never
|
|
1077
|
+
add to it. See [Filtering tags](#filtering-tags-includetags--excludetags) for
|
|
1078
|
+
their shapes.
|
|
1079
|
+
|
|
1080
|
+
```javascript
|
|
1081
|
+
import {createReader, tagFilter} from 'exifreader/core';
|
|
1082
|
+
import {jpeg} from 'exifreader/formats';
|
|
1083
|
+
import {exif, mpf} from 'exifreader/groups';
|
|
1084
|
+
|
|
1085
|
+
const reader = createReader({formats: [jpeg], groups: [exif, mpf], tagFilter});
|
|
1086
|
+
const tags = await reader.load(file, {excludeTags: {mpf: true}});
|
|
1087
|
+
```
|
|
1088
|
+
|
|
1089
|
+
**Types.** In TypeScript, the grouped result of `reader.load` has only the
|
|
1090
|
+
groups and tags the reader composes, so `tags.gps` does not compile on a reader
|
|
1091
|
+
without `gps`. Each group has only its own tag names, so `tags.exif?.Headline`,
|
|
1092
|
+
an IPTC name, does not compile either. `includeTags` and `excludeTags` compile
|
|
1093
|
+
only on a reader created with `tagFilter` (type options built before the call
|
|
1094
|
+
as `LoadOptions<false>` for a reader without it). A table whose contents
|
|
1095
|
+
TypeScript cannot see, such as `allFormats`, `allGroups` or an array typed
|
|
1096
|
+
`Format[]` or `Group[]`, gives every group instead, typed as the `ExpandedTags`
|
|
1097
|
+
of `exifreader/core`. The flat output is typed `Tags` on every reader.
|
|
1098
|
+
|
|
1099
|
+
**Runtime.** The subpaths are published as source, not transpiled. The code is
|
|
1100
|
+
ES2015, and the `composite` group also uses the ES2016 `**` operator. A reader
|
|
1101
|
+
uses these platform APIs when it needs them: `Promise` for every load;
|
|
1102
|
+
`TextDecoder` for text in IPTC, XMP and decompressed data and for the Windows XP
|
|
1103
|
+
tags; `DecompressionStream` for compressed metadata in PNG and JPEG XL files,
|
|
1104
|
+
unless `decompress` gives the functions; `DOMParser` for `xmp`, unless
|
|
1105
|
+
`domParser` is given; `btoa` for the `base64` of a thumbnail or an MPF image;
|
|
1106
|
+
and `Blob` only when one is passed to `reader.load`.
|
|
1107
|
+
|
|
1108
|
+
**Toolchains.** The subpaths are ES modules only, resolved through the
|
|
1109
|
+
package's `exports` map. They work with webpack 5, Vite, Rollup with
|
|
1110
|
+
`@rollup/plugin-node-resolve`, esbuild, Parcel 2 with `packageExports` enabled,
|
|
1111
|
+
Bun, Deno, Metro 0.82 (React Native 0.79), TypeScript with `moduleResolution`
|
|
1112
|
+
set to `bundler`, `node16` or `nodenext`, and Node with `import` (`require()`
|
|
1113
|
+
needs Node 20.19 or later on Node 20, or 22.12 or later). Some toolchains need
|
|
1114
|
+
extra setup or have limits:
|
|
1115
|
+
|
|
1116
|
+
- **TypeScript.** A CommonJS importer (a `.cts` file, or a `.ts` file in a
|
|
1117
|
+
package without `"type": "module"`) gets TS1479 on the subpath imports with
|
|
1118
|
+
`module` set to `node16` or `node18`. It needs `module` set to `nodenext`
|
|
1119
|
+
(TypeScript 5.8 or later) or `node20` (TypeScript 5.9 or later). An ES module
|
|
1120
|
+
importer works with all of them.
|
|
1121
|
+
- **Jest.** Jest 28 to 30 fail with their default configuration, since Jest
|
|
1122
|
+
does not transform `node_modules`. They work with a Babel transform plus
|
|
1123
|
+
`transformIgnorePatterns: ['/node_modules/(?!exifreader/)']`, or with
|
|
1124
|
+
`--experimental-vm-modules` when the test files are ES modules themselves.
|
|
1125
|
+
- **eslint-plugin-import.** With its default resolver it reports
|
|
1126
|
+
`import/no-unresolved` on the subpaths, since that resolver does not read
|
|
1127
|
+
`exports`.
|
|
1128
|
+
- **Parcel.** Parcel 2.16.4 resolves the subpaths with `packageExports` enabled
|
|
1129
|
+
but leaves unreferenced code in the bundle: the `Single tags` example is
|
|
1130
|
+
about 20 KiB gzip there against 13 KiB with esbuild.
|
|
1131
|
+
- **CommonJS-compiled consumers.** A consumer compiled to CommonJS before
|
|
1132
|
+
bundling (`require('exifreader/core')`) loses tree shaking under esbuild and
|
|
1133
|
+
Vite 8 (a JPEG reader with `DateTimeOriginal`: over 120 KiB raw against
|
|
1134
|
+
37 KiB). webpack 5, Rspack and `bun build` keep it.
|
|
1135
|
+
- **No tree shaking.** Without a tree-shaking bundler (Metro, unbundled Node,
|
|
1136
|
+
Deno or Bun), every format and group the imported subpaths reference is
|
|
1137
|
+
loaded.
|
|
1138
|
+
|
|
1139
|
+
#### Migrating to the composable API
|
|
1140
|
+
|
|
1141
|
+
A reader from `createReader` reads the same tags as `ExifReader.load` and
|
|
1142
|
+
describes them the same way. What differs when you move over from
|
|
1143
|
+
`ExifReader.load` or from a custom build:
|
|
1144
|
+
|
|
1145
|
+
| | `ExifReader.load` | A reader from `createReader` |
|
|
1146
|
+
|---|---|---|
|
|
1147
|
+
| Output | Flat by default, grouped with `expanded: true` | Grouped by default, flat with `expanded: false` |
|
|
1148
|
+
| Return value | The tags, or a Promise when it loads the file or with `async: true` | Always a Promise |
|
|
1149
|
+
| Input | Bytes, a `File`, a path or a URL | Bytes, a `Blob` or a `File` (see **Loading** for a path or a URL) |
|
|
1150
|
+
| Part of a file | The `length` option | Slice it first: `reader.load(file.slice(0, n))` |
|
|
1151
|
+
| `domParser` and `decompress` | Options of `load` | Passed to `createReader` |
|
|
1152
|
+
| XMP outside browsers | Looks for `@xmldom/xmldom` when no `domParser` is given | Needs `domParser`; nothing is looked up |
|
|
1153
|
+
| `includeTags` and `excludeTags` | Always available | Need `tagFilter` from `exifreader/core` in `createReader` |
|
|
1154
|
+
| Options | An unknown option is ignored, and any truthy value turns an option on | An unknown option rejects, and so does a value other than `true`, `false` or `undefined` |
|
|
1155
|
+
| PNG groups | `png`, `pngFile` and `pngText` | `png` |
|
|
1156
|
+
| A repeatable IPTC dataset such as `Keywords` | A tag when the file holds it once, an array when it holds several | Always an array |
|
|
1157
|
+
| A group with no tags | `{}` | Absent |
|
|
1158
|
+
| Thumbnail | `tags.thumbnail`, and `tags.Thumbnail` until v5 | `tags.thumbnail` |
|
|
1159
|
+
| `base64` of the thumbnail and MPF images | From `Buffer` or `btoa` | From `btoa`; `undefined` where there is none |
|
|
1160
|
+
| Errors | `ExifReader.errors` | `errors` from `exifreader/core` |
|
|
1161
|
+
| Published code | A UMD `dist` file, transpiled to ES5 | ES modules, not transpiled (see **Runtime**) |
|
|
1162
|
+
| Custom build | The `exifreader` key in `package.json` and `npx exifreader build` | Imports; `npx exifreader analyze --imports <images>` prints them |
|
|
1163
|
+
|
|
1164
|
+
#### Default entry
|
|
1165
|
+
|
|
1166
|
+
The [custom build](#configure-a-custom-build) was the previous way to a smaller
|
|
1167
|
+
bundle. It still works in v4, but it is deprecated and will be removed in v5, so
|
|
1168
|
+
use the composable API above instead.
|
|
1169
|
+
|
|
1170
|
+
If you use the default entry (`import ExifReader from 'exifreader'`) with
|
|
1171
|
+
Webpack 4 or lower and are only targeting web browsers, make sure to add this to
|
|
1172
|
+
your Webpack config (probably the `webpack.config.js` file):
|
|
828
1173
|
|
|
829
1174
|
```javascript
|
|
830
1175
|
node: {
|
|
@@ -841,13 +1186,27 @@ Configure a Custom Build
|
|
|
841
1186
|
|
|
842
1187
|
Configuring a custom build can reduce the bundle size significantly.
|
|
843
1188
|
|
|
844
|
-
**NOTE 1:**
|
|
845
|
-
|
|
1189
|
+
**NOTE 1:** The custom build was the previous way to a small bundle. It is still
|
|
1190
|
+
supported in v4, but it is deprecated and will be removed in v5. The
|
|
1191
|
+
[composable API](#composable-api) replaces it.
|
|
846
1192
|
|
|
847
1193
|
**NOTE 2:** This only changes the built file (`exifreader/dist/exif-reader.js`),
|
|
848
1194
|
not the source code. That means it's not possible to use the ES module (from the
|
|
849
1195
|
`src` folder) or any tree shaking to get the benefit of a custom build. Tree
|
|
850
|
-
shaking
|
|
1196
|
+
shaking has close to no effect on a custom build, so don't rely on it.
|
|
1197
|
+
|
|
1198
|
+
Which file a plain `import ExifReader from 'exifreader'` or
|
|
1199
|
+
`require('exifreader')` resolves to depends on the tool:
|
|
1200
|
+
|
|
1201
|
+
- `dist/exif-reader.js`, which picks up a custom build: Node, Bun, Deno, React
|
|
1202
|
+
Native's Metro (native platforms), webpack with `target: 'node'` and esbuild
|
|
1203
|
+
with `platform: 'node'`.
|
|
1204
|
+
- `src/exif-reader.js`, which never picks up a custom build: webpack 5, Vite,
|
|
1205
|
+
Parcel 2 and Metro when they build for the web, Rollup with
|
|
1206
|
+
`@rollup/plugin-node-resolve` and esbuild with `platform: 'browser'`.
|
|
1207
|
+
|
|
1208
|
+
If you bundle for the browser and use a custom build, import the built file
|
|
1209
|
+
directly: `import ExifReader from 'exifreader/dist/exif-reader';`.
|
|
851
1210
|
|
|
852
1211
|
This is for npm and yarn users that use the built file. To specify what
|
|
853
1212
|
functionality you want you can either use include pattern (start with an empty
|
|
@@ -873,7 +1232,7 @@ almost half the size of the full one (non-gzipped)):
|
|
|
873
1232
|
```
|
|
874
1233
|
|
|
875
1234
|
**Example 2:** Only include TIFF files, and the Exif `DateTime` tag and the GPS
|
|
876
|
-
tags (resulting bundle will be
|
|
1235
|
+
tags (resulting bundle will be about a third of a gzipped full build):
|
|
877
1236
|
|
|
878
1237
|
```javascript
|
|
879
1238
|
"exifreader": {
|
|
@@ -931,7 +1290,9 @@ It reads the images with the full library and prints the smallest `include`
|
|
|
931
1290
|
configuration that reads everything found in them: the file formats, the Exif
|
|
932
1291
|
and IPTC tags, and the XMP, ICC, Photoshop, maker note, MPF and thumbnail
|
|
933
1292
|
groups. Add `--write` to put it in your `package.json`, replacing any
|
|
934
|
-
`include` or `exclude` section there, then run `npx exifreader build`.
|
|
1293
|
+
`include` or `exclude` section there, then run `npx exifreader build`. Add
|
|
1294
|
+
`--imports` instead to print the equivalent `createReader` imports of the
|
|
1295
|
+
[composable API](#composable-api) in place of the configuration. To
|
|
935
1296
|
analyze and build in one step, and then check the result:
|
|
936
1297
|
|
|
937
1298
|
```bash
|
|
@@ -1044,7 +1405,11 @@ Notes
|
|
|
1044
1405
|
- In Exif data, the full GPS information is split into two different tags for
|
|
1045
1406
|
each direction: the coordinate value (`GPSLatitude`, `GPSLongitude`) and the
|
|
1046
1407
|
reference value (`GPSLatitudeRef`, `GPSLongitudeRef`). Use the references to
|
|
1047
|
-
know whether the coordinate is north/south and east/west.
|
|
1408
|
+
know whether the coordinate is north/south and east/west. The `description`
|
|
1409
|
+
of `GPSLatitude`, `GPSLongitude`, `GPSDestLatitude` and `GPSDestLongitude`
|
|
1410
|
+
is the decimal coordinate as a number, unsigned, with the reference tag
|
|
1411
|
+
giving the hemisphere. It is `NaN` when the value holds fewer than three
|
|
1412
|
+
`[numerator, denominator]` pairs. Often you will see
|
|
1048
1413
|
north and east represented as positive values, and south and west
|
|
1049
1414
|
represented as negative values (e.g. in Google Maps). This setup is also
|
|
1050
1415
|
used for the altitude using `GPSAltitude` and `GPSAltitudeRef` where the
|
|
@@ -1086,7 +1451,11 @@ Tips
|
|
|
1086
1451
|
will load a lot of files and storing the tags. It can be really large for
|
|
1087
1452
|
some manufacturers. See the
|
|
1088
1453
|
[examples site](https://mattiasw.github.io/ExifReader/) to see how you can
|
|
1089
|
-
do that.
|
|
1454
|
+
do that. On a reader from the [composable API](#composable-api), leaving
|
|
1455
|
+
`makerNotes` out of `groups` skips decoding the maker notes, but a whole
|
|
1456
|
+
`exif` group still returns the raw `MakerNote` tag. Compose the Exif tags
|
|
1457
|
+
you need by name instead, or drop it with
|
|
1458
|
+
`excludeTags: {exif: ['MakerNote']}` on a reader composed with `tagFilter`.
|
|
1090
1459
|
- In some cases it can make sense to only load the beginning of the image
|
|
1091
1460
|
file since that is where the metadata is located. It's unfortunately not
|
|
1092
1461
|
possible to know how big the metadata will be in an image, but if you limit
|
|
@@ -1101,7 +1470,9 @@ Tips
|
|
|
1101
1470
|
especially impactful when combined with `length: 'auto'` (multi-x
|
|
1102
1471
|
speedup, see that section), but it also lets a numeric `length`
|
|
1103
1472
|
boundary land well before the sub-image. Regular Exif/XMP/ICC tags are
|
|
1104
|
-
unaffected.
|
|
1473
|
+
unaffected. On a reader from the [composable API](#composable-api), leave
|
|
1474
|
+
`mpf` out of `groups`, or pass `excludeTags: {mpf: true}` to a reader
|
|
1475
|
+
composed with `mpf` and `tagFilter`.
|
|
1105
1476
|
|
|
1106
1477
|
Known Limitations
|
|
1107
1478
|
-----------------
|