feat: Do no load the entire image into memory just to read EXIF data

Author: kevinrenskers

.github/FUNDING.yml

@@ -0,0 +1,2 @@
+github: loopwerk
+buy_me_a_coffee: loopwerk

.github/workflows/release.yml

@@ -0,0 +1,28 @@
+name: Create Release
+
+on:
+  push:
+    tags:
+      - "*"
+
+jobs:
+  create-release:
+    runs-on: ubuntu-latest
+
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v6
+
+      - name: Create changelog text
+        id: changelog
+        uses: loopwerk/tag-changelog@v1
+        with:
+          token: ${{ secrets.GITHUB_TOKEN }}
+          include_commit_body: true
+          exclude_types: other,doc,chore,build
+
+      - name: Create release
+        uses: softprops/action-gh-release@v2
+        with:
+          body: ${{ steps.changelog.outputs.changes }}
+          token: ${{ secrets.GITHUB_TOKEN }}

.github/workflows/test.yml

@@ -0,0 +1,32 @@
+name: Test
+
+on:
+  push:
+    branches:
+      - main
+  pull_request:
+    branches:
+      - "*"
+
+jobs:
+  test-xcode:
+    runs-on: macos-latest
+
+    steps:
+      - uses: actions/checkout@v6
+      - uses: maxim-lobanov/setup-xcode@v1
+        with:
+          xcode-version: latest-stable
+      - name: Build
+        run: swift build -v
+      - name: Run tests
+        run: swift test -v
+
+  test-linux:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v6
+      - name: Build
+        run: swift build -v
+      - name: Run tests
+        run: swift test -v

README.md

@@ -2,28 +2,23 @@
 
 A pure Swift EXIF metadata parser. No dependencies, no Apple frameworks. Fully macOS and Linux compatible.
 
-Supports **JPEG**, **PNG**, **WebP**, and **TIFF**.
+Supports **JPEG**, **PNG**, and **WebP** images. 
+
+Scry does not load the entire image into memory, and as such can be used with large image files.
 
 ## Usage
 
 ```swift
 import Scry
 
-// From a file path
 if let metadata = try Scry.metadata(fromFileAt: "/path/to/photo.jpg") {
   print(metadata["Make"])    // "Apple"
   print(metadata["Model"])   // "iPhone 14 Pro"
   print(metadata["FNumber"]) // 1.78
 }
-
-// From Data
-let data = Data(contentsOf: url)
-if let metadata = try Scry.metadata(from: data) {
-  // format is auto-detected
-}
 ```
 
-Returns `nil` when the image has no EXIF data or the format is unsupported.
+Returns `nil` when the image has no EXIF data.
 
 ## Installation
 

Sources/Scry/Containers/JPEGContainer.swift

@@ -1,71 +1,66 @@
 import Foundation
 
 enum JPEGContainer {
-  /// Extract EXIF TIFF data from a JPEG file.
-  static func extractEXIF(from data: Data) throws -> Data {
-    guard data.count >= 4,
-          data[data.startIndex] == 0xFF,
-          data[data.startIndex + 1] == 0xD8
-    else {
+  /// Extract EXIF TIFF data from a JPEG file handle, reading only metadata segments.
+  static func extractEXIF(from fileHandle: FileHandle) throws -> Data {
+    let soi = fileHandle.readData(ofLength: 2)
+    guard soi.count == 2, soi[0] == 0xFF, soi[1] == 0xD8 else {
       throw EXIFError.invalidJPEGStructure
     }
 
-    var offset = 2
-
-    while offset + 4 <= data.count {
-      let start = data.startIndex + offset
-
-      // Each marker starts with 0xFF
-      guard data[start] == 0xFF else {
+    while true {
+      // Read marker (2 bytes)
+      let markerData = fileHandle.readData(ofLength: 2)
+      guard markerData.count == 2, markerData[0] == 0xFF else {
         throw EXIFError.invalidJPEGStructure
       }
 
-      let marker = data[start + 1]
+      let marker = markerData[1]
 
-      // Skip padding bytes (0xFF 0xFF...)
+      // Skip padding bytes
       if marker == 0xFF {
-        offset += 1
+        fileHandle.seek(toFileOffset: fileHandle.offsetInFile - 1)
         continue
       }
 
-      // SOS (Start of Scan) or EOI — no more metadata segments
-      if marker == 0xDA || marker == 0xD9 {
-        break
-      }
+      // SOS or EOI — no more metadata segments
+      if marker == 0xDA || marker == 0xD9 { break }
 
-      // Markers without a length field (RST, TEM, SOI)
+      // Markers without a length field
       if marker == 0x00 || marker == 0x01 || (0xD0 ... 0xD7).contains(marker) {
-        offset += 2
         continue
       }
 
-      // Read segment length (includes the 2 length bytes but not the marker)
-      guard offset + 4 <= data.count else { break }
-      let length = Int(data[start + 2]) << 8 | Int(data[start + 3])
+      // Read segment length
+      let lengthData = fileHandle.readData(ofLength: 2)
+      guard lengthData.count == 2 else { break }
+      let length = Int(lengthData[0]) << 8 | Int(lengthData[1])
       guard length >= 2 else { throw EXIFError.invalidJPEGStructure }
 
-      // APP1 marker (0xE1) — check for EXIF signature
-      if marker == 0xE1 {
-        let payloadStart = offset + 4
-        let payloadLength = length - 2
+      let payloadLength = length - 2
 
-        if payloadLength >= 6, payloadStart + 6 <= data.count {
-          let sigStart = data.startIndex + payloadStart
-          // "Exif\0\0"
-          if data[sigStart] == 0x45, data[sigStart + 1] == 0x78,
-             data[sigStart + 2] == 0x69, data[sigStart + 3] == 0x66,
-             data[sigStart + 4] == 0x00, data[sigStart + 5] == 0x00
-          {
-            let tiffStart = payloadStart + 6
-            let tiffLength = payloadLength - 6
-            guard tiffStart + tiffLength <= data.count else { throw EXIFError.truncatedData }
-            return Data(data[data.startIndex + tiffStart ..< data.startIndex + tiffStart + tiffLength])
-          }
+      // APP1 marker — check for EXIF signature
+      if marker == 0xE1, payloadLength >= 6 {
+        let sig = fileHandle.readData(ofLength: 6)
+        guard sig.count == 6 else { throw EXIFError.truncatedData }
+        // "Exif\0\0"
+        if sig[0] == 0x45, sig[1] == 0x78, sig[2] == 0x69, sig[3] == 0x66,
+           sig[4] == 0x00, sig[5] == 0x00
+        {
+          let tiffLength = payloadLength - 6
+          let tiffData = fileHandle.readData(ofLength: tiffLength)
+          guard tiffData.count == tiffLength else { throw EXIFError.truncatedData }
+          return tiffData
         }
+        // Not EXIF APP1, skip the rest of this segment
+        let remaining = payloadLength - 6
+        if remaining > 0 {
+          fileHandle.seek(toFileOffset: fileHandle.offsetInFile + UInt64(remaining))
+        }
+      } else {
+        // Skip segment payload
+        fileHandle.seek(toFileOffset: fileHandle.offsetInFile + UInt64(payloadLength))
       }
-
-      // Move to next marker
-      offset += 2 + length
     }
 
     throw EXIFError.noEXIFData

Sources/Scry/Containers/PNGContainer.swift

@@ -1,45 +1,32 @@
 import Foundation
 
 enum PNGContainer {
-  /// Extract EXIF TIFF data from a PNG file's eXIf chunk.
-  static func extractEXIF(from data: Data) throws -> Data {
-    // PNG signature: 89 50 4E 47 0D 0A 1A 0A
-    guard data.count >= 8,
-          data[data.startIndex] == 0x89,
-          data[data.startIndex + 1] == 0x50,
-          data[data.startIndex + 2] == 0x4E,
-          data[data.startIndex + 3] == 0x47
-    else {
+  /// Extract EXIF TIFF data from a PNG file handle, reading only chunk headers until eXIf is found.
+  static func extractEXIF(from fileHandle: FileHandle) throws -> Data {
+    let sig = fileHandle.readData(ofLength: 8)
+    guard sig.count == 8, sig[0] == 0x89, sig[1] == 0x50, sig[2] == 0x4E, sig[3] == 0x47 else {
       throw EXIFError.invalidPNGStructure
     }
 
-    var offset = 8 // skip signature
+    while true {
+      // Read chunk header: 4 bytes length + 4 bytes type
+      let header = fileHandle.readData(ofLength: 8)
+      guard header.count == 8 else { break }
 
-    // Iterate through chunks: [4 bytes length][4 bytes type][data][4 bytes CRC]
-    while offset + 8 <= data.count {
-      let start = data.startIndex + offset
-
-      // Chunk data length (big-endian)
-      let length = Int(data[start]) << 24 | Int(data[start + 1]) << 16
-        | Int(data[start + 2]) << 8 | Int(data[start + 3])
-
-      // Chunk type (4 ASCII bytes)
-      let typeStart = start + 4
-      guard typeStart + 4 <= data.endIndex else { break }
-      let chunkType = String(data: data[typeStart ..< typeStart + 4], encoding: .ascii) ?? ""
-
-      let dataStart = offset + 8
-      guard dataStart + length + 4 <= data.count else { break }
+      let length = Int(header[0]) << 24 | Int(header[1]) << 16
+        | Int(header[2]) << 8 | Int(header[3])
+      let chunkType = String(data: header[4 ..< 8], encoding: .ascii) ?? ""
 
       if chunkType == "eXIf" {
-        return Data(data[data.startIndex + dataStart ..< data.startIndex + dataStart + length])
+        let chunkData = fileHandle.readData(ofLength: length)
+        guard chunkData.count == length else { throw EXIFError.truncatedData }
+        return chunkData
       }
 
-      // IEND — end of PNG
       if chunkType == "IEND" { break }
 
-      // Move to next chunk: length field (4) + type (4) + data + CRC (4)
-      offset += 12 + length
+      // Skip chunk data + 4 bytes CRC
+      fileHandle.seek(toFileOffset: fileHandle.offsetInFile + UInt64(length + 4))
     }
 
     throw EXIFError.noEXIFData

Sources/Scry/Containers/TIFFContainer.swift

@@ -1,59 +1,46 @@
 import Foundation
 
 enum WebPContainer {
-  /// Extract EXIF TIFF data from a WebP file's EXIF chunk.
-  static func extractEXIF(from data: Data) throws -> Data {
-    // RIFF header: "RIFF" + 4 bytes size + "WEBP"
-    guard data.count >= 12,
-          data[data.startIndex] == 0x52, // R
-          data[data.startIndex + 1] == 0x49, // I
-          data[data.startIndex + 2] == 0x46, // F
-          data[data.startIndex + 3] == 0x46, // F
-          data[data.startIndex + 8] == 0x57, // W
-          data[data.startIndex + 9] == 0x45, // E
-          data[data.startIndex + 10] == 0x42, // B
-          data[data.startIndex + 11] == 0x50 // P
+  /// Extract EXIF TIFF data from a WebP file handle, reading only chunk headers until EXIF is found.
+  static func extractEXIF(from fileHandle: FileHandle) throws -> Data {
+    let header = fileHandle.readData(ofLength: 12)
+    guard header.count == 12,
+          header[0] == 0x52, header[1] == 0x49, header[2] == 0x46, header[3] == 0x46,
+          header[8] == 0x57, header[9] == 0x45, header[10] == 0x42, header[11] == 0x50
     else {
       throw EXIFError.invalidWebPStructure
     }
 
-    var offset = 12 // after "RIFF" + size + "WEBP"
+    while true {
+      // Read chunk header: 4 bytes FourCC + 4 bytes size (little-endian)
+      let chunkHeader = fileHandle.readData(ofLength: 8)
+      guard chunkHeader.count == 8 else { break }
 
-    // Scan RIFF chunks: [4 bytes FourCC][4 bytes size (little-endian)][data][padding to even]
-    while offset + 8 <= data.count {
-      let start = data.startIndex + offset
-      let fourCC = String(data: data[start ..< start + 4], encoding: .ascii) ?? ""
-
-      // Size is little-endian
-      let size = Int(data[start + 4])
-        | Int(data[start + 5]) << 8
-        | Int(data[start + 6]) << 16
-        | Int(data[start + 7]) << 24
-
-      let dataStart = offset + 8
-      guard dataStart + size <= data.count else { break }
+      let fourCC = String(data: chunkHeader[0 ..< 4], encoding: .ascii) ?? ""
+      let size = Int(chunkHeader[4])
+        | Int(chunkHeader[5]) << 8
+        | Int(chunkHeader[6]) << 16
+        | Int(chunkHeader[7]) << 24
 
       if fourCC == "EXIF" {
-        var exifStart = dataStart
-        var exifSize = size
+        var chunkData = fileHandle.readData(ofLength: size)
+        guard chunkData.count == size else { throw EXIFError.truncatedData }
 
         // Some encoders prepend "Exif\0\0" like JPEG; strip if present
-        if exifSize >= 6 {
-          let s = data.startIndex + exifStart
-          if data[s] == 0x45, data[s + 1] == 0x78,
-             data[s + 2] == 0x69, data[s + 3] == 0x66,
-             data[s + 4] == 0x00, data[s + 5] == 0x00
-          {
-            exifStart += 6
-            exifSize -= 6
-          }
+        if chunkData.count >= 6,
+           chunkData[0] == 0x45, chunkData[1] == 0x78,
+           chunkData[2] == 0x69, chunkData[3] == 0x66,
+           chunkData[4] == 0x00, chunkData[5] == 0x00
+        {
+          chunkData = Data(chunkData.dropFirst(6))
         }
 
-        return Data(data[data.startIndex + exifStart ..< data.startIndex + exifStart + exifSize])
+        return chunkData
       }
 
       // RIFF chunks are padded to even byte boundaries
-      offset = dataStart + size + (size % 2)
+      let paddedSize = size + (size % 2)
+      fileHandle.seek(toFileOffset: fileHandle.offsetInFile + UInt64(paddedSize))
     }
 
     throw EXIFError.noEXIFData

Sources/Scry/Containers/WebPContainer.swift

@@ -8,16 +8,18 @@ public enum EXIFError: Error, CustomStringConvertible {
   case invalidTIFFHeader
   case noEXIFData
   case truncatedData
+  case fileNotFound
 
   public var description: String {
     switch self {
       case .unsupportedFormat: "Unsupported image format"
       case .invalidJPEGStructure: "Invalid JPEG structure"
       case .invalidPNGStructure: "Invalid PNG structure"
       case .invalidWebPStructure: "Invalid WebP structure"
-      case .invalidTIFFHeader: "Invalid TIFF header"
+      case .invalidTIFFHeader: "Invalid TIFF header in EXIF data"
       case .noEXIFData: "No EXIF data found"
       case .truncatedData: "Unexpected end of data"
+      case .fileNotFound: "File not found"
     }
   }
 }