@crewhaus/tool-media 0.7.0 → 0.8.0

package/dist/lib/jpeg.d.ts

@@ -21,6 +21,59 @@ export declare function readJpegSegments(bytes: Uint8Array): {
     segments: JpegSegment[];
     scanStart: number;
 };
+/** One piece of a JPEG, in file order: a marker segment, or a scan's entropy-coded bytes. */
+export type JpegPart = {
+    readonly type: "segment";
+    readonly segment: JpegSegment;
+} | {
+    readonly type: "scan";
+    readonly start: number;
+    readonly end: number;
+};
+export type JpegWalk = {
+    /** Every piece after SOI, in order, up to and including EOI. */
+    readonly parts: ReadonlyArray<JpegPart>;
+    /** The marker segments alone, in order. */
+    readonly segments: ReadonlyArray<JpegSegment>;
+    /** Offset just past EOI, or null when the file ends without one. */
+    readonly eoiEnd: number | null;
+    /** Bytes after EOI: where an appended image or video lives. 0 when EOI is missing. */
+    readonly trailing: number;
+    /**
+     * Where the walk stopped short of EOI after the first scan, and why: a
+     * segment the end of the file cuts off, or bytes where a marker should
+     * be. Null when it reached EOI or the file's end in scan data. The bytes
+     * from here on were not walked.
+     */
+    readonly stopped: {
+        readonly offset: number;
+        readonly reason: string;
+    } | null;
+};
+/**
+ * Walk the WHOLE codestream: every marker segment, including those between
+ * the scans of a progressive or multi-scan file, to EOI.
+ *
+ * `readJpegSegments` stops at the first start-of-scan, which is all a header
+ * reader needs, and 0.7.0's ExifStrip copied everything after that point
+ * verbatim. But an APPn or COM segment may sit between scans, and a camera
+ * appends whole images after EOI (MPF previews, HDR gain maps, stereo pairs)
+ * and phones append motion-photo video; each can carry its own EXIF and GPS.
+ *
+ * Inside a scan, `0xFF` followed by `0x00` (stuffing), `0xD0`–`0xD7` (restart
+ * markers) or another `0xFF` (fill) belongs to the scan; any other `0xFF xx`
+ * is the next marker. The walk is linear: the scan search is a native
+ * `indexOf` from where the last one stopped.
+ *
+ * A broken header (before the first scan) is refused. Past the first scan
+ * the picture is already there, and a file cut short there — a partial
+ * download, a truncated progressive JPEG — is still a photo: the walk stops
+ * at the break and says where (`stopped`), rather than refusing a file
+ * 0.7.0 read, which only ever looked as far as the first scan.
+ */
+export declare function walkJpeg(bytes: Uint8Array): JpegWalk;
+/** A hint at what the bytes after EOI are, for a person reading the result. */
+export declare function describeTrailer(trailer: Uint8Array): string;
 export type GpsFix = {
     readonly latitude: number;
     readonly longitude: number;
@@ -72,10 +125,95 @@ export type StripResult = {
         bytes: number;
     }>;
     readonly bytesRemoved: number;
+    /** Bytes after EOI that were dropped: an appended image or video, and its metadata. */
+    readonly trailingBytesRemoved: number;
+    /** What those bytes looked like, when there were any. */
+    readonly trailingKind?: string;
+    /** The file ends without EOI; everything up to its end was walked and kept. */
+    readonly eoiMissing: boolean;
+    /**
+     * Where the file breaks off after the first scan, when it does: the walk
+     * stopped there, and the bytes after it were kept verbatim (or, when they
+     * begin a metadata segment, dropped).
+     */
+    readonly breaksOffAt?: {
+        readonly offset: number;
+        readonly reason: string;
+    };
 };
 /**
- * A JPEG with its metadata segments dropped. The scan data is copied
- * verbatim — nothing is re-encoded, so the image is bit-for-bit the same
- * picture, just without the record of who took it and where.
+ * A JPEG with its metadata dropped: every APPn and COM segment the options
+ * do not keep, wherever it sits (before the first scan or between scans),
+ * and everything after EOI. The scans' entropy-coded bytes are copied
+ * verbatim — nothing is re-encoded, so the primary image is bit-for-bit the
+ * same picture, without the record of who took it and where.
+ *
+ * Dropping the trailer loses an appended preview, gain map or motion-photo
+ * video, and the metadata inside each. Nothing in the stripped file points
+ * at them any more: the MPF index (APP2) and the XMP (APP1) that did are
+ * metadata segments and are removed.
  */
 export declare function stripJpegMetadata(bytes: Uint8Array, options?: StripOptions): StripResult;
+/** One EXIF block found anywhere in a file, with where it was. */
+export type ExifLocation = {
+    readonly where: "before the first scan" | "between scans" | "in an appended image" | "in bytes no walk accounts for";
+    readonly offset: number;
+    readonly exif: ExifData | null;
+    /** Why `exif` is null: the block is there but could not be parsed. */
+    readonly unreadable?: string;
+};
+export type JpegMetadataReport = {
+    /** Every EXIF block in the file, the primary one first. */
+    readonly exifBlocks: ReadonlyArray<ExifLocation>;
+    /** APPn and COM segments that sit between or after the scans of the main image. */
+    readonly interScanMetadataSegments: ReadonlyArray<string>;
+    /** APPn segments before the first scan, by name. */
+    readonly metadataSegments: ReadonlyArray<string>;
+    readonly trailingBytes: number;
+    readonly trailingKind?: string;
+    /** JPEGs found in the trailer and walked for EXIF. */
+    readonly embeddedImages: number;
+    /** JPEG starts in the trailer beyond the ones walked; their metadata is unknown. */
+    readonly embeddedImagesNotInspected: number;
+    readonly eoiMissing: boolean;
+    /** Where the main image breaks off after its first scan, when it does. */
+    readonly breaksOffAt?: {
+        readonly offset: number;
+        readonly reason: string;
+    };
+    /**
+     * Bytes no walk accounts for and that are not padding: after a break,
+     * after EOI outside every appended image walked (a video, data this does
+     * not recognise, an image that would not walk), or past the end of what
+     * was read. They were searched for EXIF blocks, not parsed, so they may
+     * hold a location this report does not see.
+     */
+    readonly unaccountedBytes: number;
+    /** EXIF signatures in those bytes beyond the ones parsed. */
+    readonly exifSignaturesNotParsed: number;
+    /** Every APPn segment other than EXIF, in the main image and the appended ones walked. */
+    readonly otherMetadata: ReadonlyArray<OtherMetadata>;
+};
+/**
+ * A metadata segment other than EXIF, and whether it names a location.
+ * `location` is true when it does, false when it was read (or its format
+ * has no place for one) and it does not, and null when this reader does
+ * not parse it, so it may.
+ */
+export type OtherMetadata = {
+    /** `"APP1 XMP"`, `"APP13 Photoshop"`, or the marker and its identifier. */
+    readonly segment: string;
+    readonly where: ExifLocation["where"];
+    readonly offset: number;
+    readonly location: boolean | null;
+};
+/**
+ * Every place in a JPEG that can carry metadata: EXIF before and between
+ * scans, other APPn/COM segments, and the JPEGs appended after EOI (walked
+ * once each, not their own trailers again). Bytes no walk accounts for —
+ * after a break, a video, unrecognised data, an appended image that would
+ * not walk — are counted and searched for EXIF blocks, which are parsed
+ * where found. What this reports is what ExifRead answers from, so it
+ * cannot call a file clean on the strength of bytes it never read.
+ */
+export declare function inspectJpegMetadata(bytes: Uint8Array): JpegMetadataReport;