nom-exif

https://docs.rs/nom-exif/latest
Admin
nom-exif is a pure Rust library for parsing Exif and other metadata from various multimedia files...
Tokens:117,925
Snippets:445
Trust Score:9.7
Update:1 year ago
Show doc for...
Tokens:
Raw
### MediaParser Test Suite Setup (Rust)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/parser

Sets up a static, lazily initialized, and mutex-protected MediaParser instance for use across multiple test cases. This ensures thread-safe access to the parser during testing.

```rust
static PARSER: LazyLock<Mutex<MediaParser>> = LazyLock::new(|| Mutex::new(MediaParser::new()));
    fn parser() -> MutexGuard<'static, MediaParser> {
        PARSER.lock().unwrap()
    }
```

--------------------------------

### Example: Parsing Exif and Track Info with MediaParser

Source: https://docs.rs/nom-exif/latest/src/nom_exif/parser

Demonstrates how to use MediaParser to parse Exif and Track information from media files. It shows the creation of MediaSource, parsing of data, and assertions on the extracted metadata.

```rust
use nom_exif::*;
use chrono::DateTime;

let mut parser = MediaParser::new();

// ------------------- Parse Exif Info
let ms = MediaSource::file_path("./testdata/exif.heic").unwrap();
assert!(ms.has_exif());
let mut iter: ExifIter = parser.parse(ms).unwrap();

let entry = iter.next().unwrap();
assert_eq!(entry.tag().unwrap(), ExifTag::Make);
assert_eq!(entry.get_value().unwrap().as_str().unwrap(), "Apple");

// Convert `ExifIter` into an `Exif`. Clone it before converting, so that
// we can start the iteration from the beginning.
let exif: Exif = iter.clone().into();
assert_eq!(exif.get(ExifTag::Make).unwrap().as_str().unwrap(), "Apple");

// ------------------- Parse Track Info
let ms = MediaSource::file_path("./testdata/meta.mov").unwrap();
assert!(ms.has_track());
let info: TrackInfo = parser.parse(ms).unwrap();

assert_eq!(info.get(TrackInfoTag::Make), Some(&"Apple".into()));
assert_eq!(info.get(TrackInfoTag::Model), Some(&"iPhone X".into()));
assert_eq!(info.get(TrackInfoTag::GpsIso6709), Some(&"+27.1281+100.2508+000.000/".into()));
assert_eq!(info.get_gps_info().unwrap().latitude_ref, 'N');
assert_eq!(
    info.get_gps_info().unwrap().latitude,
    [(27, 1), (7, 1), (68, 100)].into()
);

```

--------------------------------

### CLI Tool rexiftool - Human Readable Output

Source: https://docs.rs/nom-exif/latest/nom_exif

Demonstrates running the `rexiftool` CLI tool to display multimedia metadata in a human-readable format. The example shows command-line arguments for specifying the input file.

```shell
cargo run --example rexiftool testdata/meta.mov

```

--------------------------------

### Async API: AsyncMediaSource and AsyncMediaParser Setup in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/index

Illustrates the setup for the asynchronous API of nom-exif, requiring the 'async' feature flag. This enables parsing of multimedia data sources implementing the `AsyncRead` trait using `AsyncMediaSource` and `AsyncMediaParser`.

```rust
#[tokio::main]
async fn main() -> Result<()> {
    // Add your async code here using AsyncMediaSource and AsyncMediaParser
    Ok(())
}

```

--------------------------------

### Implement get Method for TrackInfo - Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/struct

Implements the `get` method for the TrackInfo struct, allowing retrieval of a specific entry value based on a TrackInfoTag. The return type is an Option<&EntryValue>.

```Rust
pub fn get(&self, tag: TrackInfoTag) -> Option<&EntryValue>
```

--------------------------------

### CLI Tool rexiftool - Human Readable Output

Source: https://docs.rs/nom-exif/latest/src/nom_exif/lib

Shows how to use the `rexiftool` command-line tool to display EXIF metadata in a human-readable format. The example command parses a video file (`testdata/meta.mov`) and outputs key-value pairs for various metadata tags like Make, Model, and GPS information.

```text
cargo run --example rexiftool testdata/meta.mov
```

--------------------------------

### Accessing Metadata with Error Handling in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Shows how to use `Path::metadata` and `and_then` to chain operations that retrieve file metadata, handling potential errors like 'NotFound'. This example highlights robust file system interaction.

```rust
use std::{io::ErrorKind, path::Path};

// Note: on Windows "/" maps to "C:\"
let root_modified_time = Path::new("/").metadata().and_then(|md| md.modified());
assert!(root_modified_time.is_ok());

let should_fail = Path::new("/bad/path").metadata().and_then(|md| md.modified());
assert!(should_fail.is_err());
assert_eq!(should_fail.unwrap_err().kind(), ErrorKind::NotFound);
```

--------------------------------

### Batch EXIF Parsing with rexiftool (Rust)

Source: https://docs.rs/nom-exif/latest/nom_exif/index

Demonstrates how to use the `rexiftool` command-line tool to batch parse EXIF data from all files within a specified directory. This example shows the command execution and sample output for various file types, including HEIC, WEBM, MKA, and JPG. It illustrates handling of both successful parses and errors like 'Exif not found' or unrecognized formats.

```bash
cargo run --example rexiftool testdata/

```

```text
File: "testdata/embedded-in-heic.mov"
------------------------------------------------
Make                            => Apple
Model                           => iPhone 15 Pro
Software                        => 17.1
CreateDate                      => 2023-11-02T12:01:02+00:00
DurationMs                      => 2795
ImageWidth                      => 1920
ImageHeight                     => 1440
GpsIso6709                      => +22.5797+113.9380+028.396/

File: "testdata/compatible-brands-fail.heic"
------------------------------------------------
Unrecognized file format, consider filing a bug @ https://github.com/mindeng/nom-exif.

File: "testdata/webm_480.webm"
------------------------------------------------
CreateDate                      => 2009-09-09T09:09:09+00:00
DurationMs                      => 30543
ImageWidth                      => 480
ImageHeight                     => 270

File: "testdata/mka.mka"
------------------------------------------------
DurationMs                      => 3422
ImageWidth                      => 0
ImageHeight                     => 0

File: "testdata/exif-one-entry.heic"
------------------------------------------------
Orientation                     => 1

File: "testdata/no-exif.jpg"
------------------------------------------------
Error: parse failed: Exif not found

File: "testdata/exif.jpg"
------------------------------------------------
ImageWidth                      => 3072
Model                           => vivo X90 Pro+
ImageHeight                     => 4096
ModifyDate                      => 2023-07-09T20:36:33+08:00
YCbCrPositioning                => 1
ExifOffset                      => 201
MakerNote                       => Undefined[0x30]
RecommendedExposureIndex        => 454
SensitivityType                 => 2
ISOSpeedRatings                 => 454
ExposureProgram                 => 2
FNumber                         => 175/100 (1.7500)
ExposureTime                    => 9997/1000000 (0.0100)
SensingMethod                   => 2
SubSecTimeDigitized             => 616
OffsetTimeOriginal              => +08:00
SubSecTimeOriginal              => 616
OffsetTime                      => +08:00
SubSecTime                      => 616
FocalLength                     => 8670/1000 (8.6700)
Flash                           => 16
LightSource                     => 21
MeteringMode                    => 1
SceneCaptureType                => 0
UserComment                     => filter: 0; fileterIntensity: 0.0; filterMask: 0; algolist: 0; 
...

```

--------------------------------

### Unified File Parsing with MediaParser in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif

Demonstrates a unified workflow for parsing various multimedia file types (images, videos, audio) using `MediaSource` and `MediaParser` from the nom-exif library. It checks for Exif data or track information and parses accordingly. This example requires the `nom_exif` crate.

```rust
use nom_exif::*

fn main() -> Result<()> {
    let mut parser = MediaParser::new();

    let files = [
        "./testdata/exif.heic",
        "./testdata/exif.jpg",
        "./testdata/tif.tif",
        "./testdata/meta.mov",
        "./testdata/meta.mp4",
        "./testdata/webm_480.webm",
        "./testdata/mkv_640x360.mkv",
        "./testdata/mka.mka",
        "./testdata/3gp_640x360.3gp"
    ];

    for f in files {
        let ms = MediaSource::file_path(f)?;

        if ms.has_exif() {
            // Parse the file as an Exif-compatible file
            let mut iter: ExifIter = parser.parse(ms)?;
            // ...
        } else if ms.has_track() {
            // Parse the file as a track
            let info: TrackInfo = parser.parse(ms)?;
            // ...
        }
    }

    Ok(())
}
```

--------------------------------

### CLI Tool rexiftool - JSON Dump

Source: https://docs.rs/nom-exif/latest/src/nom_exif/lib

Illustrates how to use the `rexiftool` command-line tool with the `-j` flag to output EXIF metadata as a JSON object. The example command parses a video file (`testdata/meta.mov`) and presents the metadata in a structured JSON format.

```text
cargo run --example rexiftool testdata/meta.mov -j
```

--------------------------------

### Batch Parse Files in Directory with rexiftool (Rust)

Source: https://docs.rs/nom-exif/latest/index

Demonstrates how to use the `rexiftool` example to batch parse all files within a specified directory. It shows the command-line usage and the expected output format for various media file types. This functionality is useful for extracting EXIF and other metadata from multiple files efficiently.

```bash
cargo run --example rexiftool testdata/
```

```text
File: "testdata/embedded-in-heic.mov"
------------------------------------------------
Make                            => Apple
Model                           => iPhone 15 Pro
Software                        => 17.1
CreateDate                      => 2023-11-02T12:01:02+00:00
DurationMs                      => 2795
ImageWidth                      => 1920
ImageHeight                     => 1440
GpsIso6709                      => +22.5797+113.9380+028.396/

File: "testdata/compatible-brands-fail.heic"
------------------------------------------------
Unrecognized file format, consider filing a bug @ https://github.com/mindeng/nom-exif.

File: "testdata/webm_480.webm"
------------------------------------------------
CreateDate                      => 2009-09-09T09:09:09+00:00
DurationMs                      => 30543
ImageWidth                      => 480
ImageHeight                     => 270

File: "testdata/mka.mka"
------------------------------------------------
DurationMs                      => 3422
ImageWidth                      => 0
ImageHeight                     => 0

File: "testdata/exif-one-entry.heic"
------------------------------------------------
Orientation                     => 1

File: "testdata/no-exif.jpg"
------------------------------------------------
Error: parse failed: Exif not found

File: "testdata/exif.jpg"
------------------------------------------------
ImageWidth                      => 3072
Model                           => vivo X90 Pro+
ImageHeight                     => 4096
ModifyDate                      => 2023-07-09T20:36:33+08:00
YCbCrPositioning                => 1
ExifOffset                      => 201
MakerNote                       => Undefined[0x30]
RecommendedExposureIndex        => 454
SensitivityType                 => 2
ISOSpeedRatings                 => 454
ExposureProgram                 => 2
FNumber                         => 175/100 (1.7500)
ExposureTime                    => 9997/1000000 (0.0100)
SensingMethod                   => 2
SubSecTimeDigitized             => 616
OffsetTimeOriginal              => +08:00
SubSecTimeOriginal              => 616
OffsetTime                      => +08:00
SubSecTime                      => 616
FocalLength                     => 8670/1000 (8.6700)
Flash                           => 16
LightSource                     => 21
MeteringMode                    => 1
SceneCaptureType                => 0
UserComment                     => filter: 0; fileterIntensity: 0.0; filterMask: 0; algolist: 0;
...
```

--------------------------------

### CLI Tool rexiftool - JSON Dump

Source: https://docs.rs/nom-exif/latest/nom_exif

Illustrates how to use the `rexiftool` CLI tool to output metadata as a JSON object. The `-j` flag is used to enable JSON output, and the example shows the resulting JSON structure for a given file.

```shell
cargo run --example rexiftool testdata/meta.mov -j

```

--------------------------------

### Rust: Safely Get Ok Value (Nightly)

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Introduces the experimental `into_ok()` method (nightly-only), which returns the `Ok` value without panicking. It's a compile-time safeguard against unexpected error types.

```rust
fn only_good_news() -> Result<String, !> {
    Ok("this is fine".into())
}

let s: String = only_good_news().into_ok();
println!("{s}");
```

--------------------------------

### Batch Parse Files in Directory with rexiftool (Rust)

Source: https://docs.rs/nom-exif/latest/nom_exif

Demonstrates how to use the `rexiftool` command-line tool to batch parse EXIF data from all files within a specified directory. This example shows the output for various image and video file types, highlighting the extracted metadata. It requires the `rexiftool` executable to be available in the system's PATH or the current directory.

```rust
cargo run --example rexiftool testdata/
```

--------------------------------

### Parse MP4 Box Headers (Rust)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/bbox

Provides examples of parsing MP4 box headers using `FullBoxHeader::parse` and `BoxHeader::parse`. It demonstrates parsing both valid and incomplete headers, asserting the extracted box type, size, version, and flags. Error handling for incomplete or invalid headers is also shown.

```rust
    #[test]
    fn box_header() {
        let _ = tracing_subscriber::fmt().with_test_writer().try_init();

        let data = [
            0x00, 0x00, 0x01, 0xdd, 0x6d, 0x65, 0x74, 0x61, 0x02, 0x04, 0x04, 0x00,
        ];
        let (remain, header) = FullBoxHeader::parse(&data).unwrap();
        assert_eq!(header.box_type, "meta");
        assert_eq!(header.box_size, 0x01dd);
        assert_eq!(header.version, 0x2);
        assert_eq!(header.flags, 0x40400,);
        assert_eq!(header.header_size, 12);
        assert_eq!(remain, b"");

        let data = [
            0x00, 0x00, 0x00, 0x01, 0x6d, 0x64, 0x61, 0x74, 0x00, 0x00, 0x00, 0x00, 0x00, 0x0e,
            0xfa, 0x74, 0x01, 0x04, 0x04, 0x00,
        ];
        let (remain, header) = FullBoxHeader::parse(&data).unwrap();
        assert_eq!(header.box_type, "mdat");
        assert_eq!(header.box_size, 0xefa74);
        assert_eq!(header.version, 0x1);
        assert_eq!(header.flags, 0x40400,);
        assert_eq!(header.header_size, 20);
        assert_eq!(remain, b"");

        let data = [0x00, 0x00, 0x01, 0xdd, 0x6d, 0x65, 0x74];
        let err = BoxHeader::parse(&data).unwrap_err();
        assert!(err.is_incomplete());

        let data = [0x00, 0x00, 0x00, 0x07, 0x00, 0x00, 0x00, 0x00];
        let err = BoxHeader::parse(&data).unwrap_err();
        assert_eq!(
            err,
            nom::Err::Error(make_error(&[] as &[u8], nom::error::ErrorKind::Fail))
        );
    }
```

--------------------------------

### JPEG Marker Code Enum Definition

Source: https://docs.rs/nom-exif/latest/src/nom_exif/jpeg

Defines an enum 'MarkerCode' representing standard marker codes found in JPEG files. It includes common markers like Start of Image (SOI), APP1, Start of Scan (SOS), and End of Image (EOI). An implementation provides a method to get the raw byte value of each marker.

```rust
/// A marker code is a byte following 0xFF that indicates the kind of marker.
enum MarkerCode {
    // Start of Image
    Soi = 0xD8,

    // APP1 marker
    APP1 = 0xE1,

    // Start of Scan
    Sos = 0xDA,

    // End of Image
    Eoi = 0xD9,
}

impl MarkerCode {
    fn code(self) -> u8 {
        self as u8
    }
}
```

--------------------------------

### Get Exif Data Offset Range from MetaBox in Rust

Source: https://docs.rs/nom-exif/latest/src/nom_exif/bbox/meta

Retrieves the byte range (start and end offset) for Exif data within the input. Similar to `exif_data`, it uses 'iinf' and 'iloc' to find the Exif data's location. It only supports file offsets (construction_method 0) and returns `None` for unsupported methods or if Exif data is not found.

```rust
impl MetaBox {
    #[tracing::instrument(skip_all)]
    pub fn exif_data_offset(&self) -> Option<Range<usize>> {
        self.iinf
            .as_ref()
            .and_then(|iinf| iinf.get_infe("Exif"))
            .and_then(|exif_infe| {
                self.iloc
                    .as_ref()
                    .and_then(|iloc| iloc.item_offset_len(exif_infe.id))
            })
            .and_then(|(construction_method, offset, length)| {
                let start = offset as usize;
                let end = (offset + length) as usize;
                if construction_method == 0 {
                    // file offset
                    Some(start..end)
                } else if construction_method == 1 {
                    // idat offset
                    tracing::debug!("idat offset construction method is not supported yet");
                    None
                } else {
                    tracing::debug!("item offset construction method is not supported yet");
                    None
                }
            })
    }
}
```

--------------------------------

### Rust: Get Single EXIF Entry Value by Tag (Deprecated)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_exif

A deprecated method to get a single EXIF entry value by `ExifTag` from ifd0. Use `Self::get` for current implementations.

```rust
/// Get entry value for the specified `tag` in ifd0 (the main image).
#[deprecated(since = "1.5.0", note = "please use [`Self::get`] instead")]
pub fn get_value(&self, tag: &ExifTag) -> crate::Result<Option<EntryValue>> {
    #[allow(deprecated)]
    self.get_value_by_tag_code(tag.code())
}
```

--------------------------------

### Rust: Create MediaParser and MediaSource

Source: https://context7.com/context7/rs_nom-exif/llms.txt

Demonstrates how to initialize a `MediaParser` and create a `MediaSource` from a file path. It also shows how to check for the presence of Exif or track metadata within the source. Alternative `MediaSource` creation methods for TCP streams or readers are also mentioned.

```rust
use nom_exif::*;

fn main() -> Result<()> {
    // Create a reusable parser instance
    let mut parser = MediaParser::new();

    // Create MediaSource from file path
    let ms = MediaSource::file_path("./testdata/exif.heic")?;

    // Check what type of metadata is available
    if ms.has_exif() {
        println!("File contains Exif data");
    } else if ms.has_track() {
        println!("File contains track metadata");
    }

    // Alternative sources:
    // From TCP stream: MediaSource::tcp_stream(stream)?
    // From seekable reader: MediaSource::seekable(reader)?
    // From non-seekable reader: MediaSource::unseekable(reader)?

    Ok(())
}
```

--------------------------------

### MediaSource Builder Methods in Rust

Source: https://docs.rs/nom-exif/latest/src/nom_exif/parser

Provides static methods to construct `MediaSource` instances from different types of readers. It includes methods for creating sources from file paths, `File` objects, `TcpStream` objects, and generic seekable or unseekable readers. These methods abstract the underlying reader type and handle the initial buffer build process.

```rust
impl<R: Read + Seek> MediaSource<R, Seekable> {
    pub fn seekable(reader: R) -> crate::Result<Self> {
        Self::build(reader)
    }
}

impl<R: Read> MediaSource<R, Unseekable> {
    pub fn unseekable(reader: R) -> crate::Result<Self> {
        Self::build(reader)
    }
}

impl MediaSource<File, Seekable> {
    pub fn file_path<P: AsRef<Path>>(path: P) -> crate::Result<Self> {
        Self::seekable(File::open(path)?)
    }

    pub fn file(file: File) -> crate::Result<Self> {
        Self::seekable(file)
    }
}

impl MediaSource<TcpStream, Unseekable> {
    pub fn tcp_stream(stream: TcpStream) -> crate::Result<Self> {
        Self::unseekable(stream)
    }
}
```

--------------------------------

### Default Value with `unwrap_or` in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Shows how to use `unwrap_or` to get the `Ok` value or a specified default if the `Result` is an `Err`. Note that the default value is eagerly evaluated.

```rust
let default = 2;
let x: Result<u32, &str> = Ok(9);
assert_eq!(x.unwrap_or(default), 9);

let x: Result<u32, &str> = Err("error");
assert_eq!(x.unwrap_or(default), default);
```

--------------------------------

### Test KeysBox Parsing with Sample Data in Rust

Source: https://docs.rs/nom-exif/latest/src/nom_exif/bbox/keys

This Rust code snippet demonstrates unit testing for the `KeysBox` and `KeyEntry` parsing logic. It uses the `test_case` macro to run tests with different sample files and expected sizes. The tests read sample QuickTime files, traverse the box structure to find the 'moov', 'meta', and 'keys' atoms, and then use the `KeysBox::parse_box` method to deserialize the keys data, asserting the correctness of the parsed entries.

```rust
#[cfg(test)]
mod tests {
    use crate::{
        bbox::{travel_while, ParseBox},
        testkit::read_sample,
    };

    use super::*;
    use test_case::test_case;

    #[test_case("meta.mov", 4133, 0x01b9, 0xc9)]
    fn keys_box(path: &str, moov_size: u64, meta_size: u64, keys_size: u64) {
        let _ = tracing_subscriber::fmt().with_test_writer().try_init();

        let buf = read_sample(path).unwrap();
        let (_, moov) = travel_while(&buf, |b| b.box_type() != "moov").unwrap();
        let moov = moov.unwrap();
        let (_, meta) = travel_while(moov.body_data(), |b| b.box_type() != "meta").unwrap();
        let meta = meta.unwrap();
        let (_, keys) = travel_while(meta.body_data(), |b| b.box_type() != "keys").unwrap();
        let keys = keys.unwrap();

        assert_eq!(moov.box_size(), moov_size);
        assert_eq!(meta.box_size(), meta_size);
        assert_eq!(keys.box_size(), keys_size);

        let (rem, keys) = KeysBox::parse_box(keys.data).unwrap();
        assert!(rem.is_empty());

        assert_eq!(
            keys.entries,
            vec![
                KeyEntry {
                    size: 32,
                    namespace: "mdta".to_owned(),
                    key: "com.apple.quicktime.make".to_owned()
                },
                KeyEntry {
                    size: 33,
                    namespace: "mdta".to_owned(),
                    key: "com.apple.quicktime.model".to_owned()
                },
                KeyEntry {
                    size: 36,
                    namespace: "mdta".to_owned(),
                    key: "com.apple.quicktime.software".to_owned()
                },
                KeyEntry {
                    size: 44,
                    namespace: "mdta".to_owned(),
                    key: "com.apple.quicktime.location.ISO6709".to_owned()
                },
                KeyEntry {
                    size: 40,
                    namespace: "mdta".to_owned(),
                    key: "com.apple.quicktime.creationdate".to_owned()
                }
            ]
        );
    }

    #[test_case("embedded-in-heic.mov", 0x1790, 0x0372, 0x1ce)]
    fn heic_mov_keys(path: &str, moov_size: u64, meta_size: u64, keys_size: u64) {
        let _ = tracing_subscriber::fmt().with_test_writer().try_init();

        let buf = read_sample(path).unwrap();
        let (_, moov) = travel_while(&buf, |b| b.box_type() != "moov").unwrap();
        let moov = moov.unwrap();
        let (_, meta) = travel_while(moov.body_data(), |b| b.box_type() != "meta").unwrap();
        let meta = meta.unwrap();
        let (_, keys) = travel_while(meta.body_data(), |b| b.box_type() != "keys").unwrap();
        let keys = keys.unwrap();

        assert_eq!(moov.box_size(), moov_size);
    }
}
```

--------------------------------

### Rust: Get GPS Information

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_exif

Provides a method to retrieve the parsed GPS information associated with the EXIF data. This is crucial for location-based metadata in images.

```rust
/// Get parsed GPS information.
pub fn gps_info(&self) -> Option<&GPSInfo> {
    self.gps_info.as_ref()
}
```

--------------------------------

### Unsafe `unwrap_unchecked` in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Provides an example of the `unsafe fn unwrap_unchecked` method for `Result`. This method bypasses the check for `Err` and should only be used when the programmer guarantees the `Result` is `Ok`.

```rust
let x: Result<u32, &str> = Ok(2);
assert_eq!(unsafe { x.unwrap_unchecked() }, 2);
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
unsafe { x.unwrap_unchecked() }; // Undefined behavior!
```

--------------------------------

### MediaParser Constructor and Usage Recommendation

Source: https://docs.rs/nom-exif/latest/src/nom_exif/parser

Provides a constructor for MediaParser and emphasizes the importance of reusing instances to optimize performance by avoiding repeated memory allocations. This is a key aspect of the nom-exif library's design.

```rust
impl MediaParser {
    pub fn new() -> Self {
        Self::default()
    }

    /// `MediaParser`/`AsyncMediaParser` comes with its own buffer management,
    /// so that buffers can be reused during multiple parsing processes to
    /// avoid frequent memory allocations. Therefore, try to reuse a
    /// `MediaParser` instead of creating a new one every time you need it.
    
```

--------------------------------

### Iterating Over Result Values with `iter`

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Shows how to use `iter` to get an iterator over the contained value if the Result is `Ok`. The iterator yields at most one item. This is useful for functional-style processing of Results.

```rust
let x: Result<u32, &str> = Ok(7);
assert_eq!(x.iter().next(), Some(&7));

let x: Result<u32, &str> = Err("nothing!");
assert_eq!(x.iter().next(), None);
```

--------------------------------

### Get EXIF Entry Result (Rust)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_iter

Retrieves the parsed result of an EXIF entry. Returns an `Err` if parsing failed or `Ok` with the entry value. This method does not consume the entry.

```rust
/// Returns:
///
/// - If any error occurred while parsing this entry, an
///   Err(&[`EntryError`]) is returned.
///
/// - Otherwise, an Ok(&[`EntryValue`]) is returned.
pub fn get_result(&self) -> Result<&EntryValue, &EntryError> {
    match self.res {
        Some(ref v) => v.as_ref(),
        None => panic!("take result of entry twice"),
    }
}
```

--------------------------------

### Implement Default for MediaParser

Source: https://docs.rs/nom-exif/latest/src/nom_exif/parser

Provides a default constructor for MediaParser, initializing it with empty buffers and zero position. This allows creating a MediaParser instance using default values.

```rust
impl Default for MediaParser {
    fn default() -> Self {
        Self {
            bb: Buffers::new(),
            buf: None,
            position: 0,
        }
    }
}
```

--------------------------------

### Rust: Safely Get Err Value (Nightly)

Source: https://docs.rs/nom-exif/latest/nom_exif/type

Presents the experimental `into_err()` method (nightly-only) for safely retrieving an `Err` value without panicking. This serves as a compile-time check for the absence of `Ok` variants.

```rust
fn only_bad_news() -> Result<!, String> {
    Err("Oops, it failed".into())
}

let error: String = only_bad_news().into_err();
println!("{error}");
```

--------------------------------

### Get EBML Document Type

Source: https://docs.rs/nom-exif/latest/src/nom_exif/file

Parses an EBML (Extensible Binary Meta Language) document from a byte slice and returns the document type as a String. It uses a `Cursor` for efficient byte reading.

```rust
fn get_ebml_doc_type(input: &[u8]) -> crate::Result<String> {
    let mut cursor = Cursor::new(input);
    let doc = parse_ebml_doc_type(&mut cursor)?;
    Ok(doc)
}
```

--------------------------------

### Sync API: MediaSource and MediaParser Usage in Rust

Source: https://docs.rs/nom-exif/latest/nom_exif/index

Demonstrates how to use `MediaSource` to load multimedia files (HEIC, MOV) and `MediaParser` to extract EXIF and track information. Handles different source types like file paths, TCP streams, and seekable/unseekable readers.

```rust
use nom_exif::*;

fn main() -> Result<()> {
    let mut parser = MediaParser::new();
     
    let ms = MediaSource::file_path("./testdata/exif.heic")?;
    assert!(ms.has_exif());
     
    let mut iter: ExifIter = parser.parse(ms)?;
    let exif: Exif = iter.into();
    assert_eq!(exif.get(ExifTag::Make).unwrap().as_str().unwrap(), "Apple");

    let ms = MediaSource::file_path("./testdata/meta.mov")?;
    assert!(ms.has_track());
     
    let info: TrackInfo = parser.parse(ms)?;
    assert_eq!(info.get(TrackInfoTag::Make), Some(&"Apple".into()));
    assert_eq!(info.get(TrackInfoTag::Model), Some(&"iPhone X".into()));
    assert_eq!(info.get(TrackInfoTag::GpsIso6709), Some(&"+27.1281+100.2508+000.000/".into()));
    assert_eq!(info.get_gps_info().unwrap().latitude_ref, 'N');
    assert_eq!(
        info.get_gps_info().unwrap().latitude,
        [(27, 1), (7, 1), (68, 100)].into()
    );

    // `MediaSource` can also be created from a `TcpStream`:
    // let ms = MediaSource::tcp_stream(stream)?;

    // Or from any `Read + Seek`:
    // let ms = MediaSource::seekable(stream)?;
     
    // From any `Read`:
    // let ms = MediaSource::unseekable(stream)?;
     
    Ok(())
}

```

--------------------------------

### Sync API: MediaSource and MediaParser with Rust

Source: https://docs.rs/nom-exif/latest/nom_exif

Demonstrates using the synchronous MediaSource and MediaParser to extract EXIF and track information from multimedia files. It shows how to create MediaSource from file paths and parse them into Exif or TrackInfo structures.

```rust
use nom_exif::*

fn main() -> Result<()> {
    let mut parser = MediaParser::new();
     
    let ms = MediaSource::file_path("./testdata/exif.heic")?;
    assert!(ms.has_exif());
     
    let mut iter: ExifIter = parser.parse(ms)?;
    let exif: Exif = iter.into();
    assert_eq!(exif.get(ExifTag::Make).unwrap().as_str().unwrap(), "Apple");

    let ms = MediaSource::file_path("./testdata/meta.mov")?;
    assert!(ms.has_track());
     
    let info: TrackInfo = parser.parse(ms)?;
    assert_eq!(info.get(TrackInfoTag::Make), Some(&"Apple".into()));
    assert_eq!(info.get(TrackInfoTag::Model), Some(&"iPhone X".into()));
    assert_eq!(info.get(TrackInfoTag::GpsIso6709), Some(&"+27.1281+100.2508+000.000/".into()));
    assert_eq!(info.get_gps_info().unwrap().latitude_ref, 'N');
    assert_eq!(
        info.get_gps_info().unwrap().latitude,
        [(27, 1), (7, 1), (68, 100)].into(),
    );

    // `MediaSource` can also be created from a `TcpStream`:
    // let ms = MediaSource::tcp_stream(stream)?;

    // Or from any `Read + Seek`:
    // let ms = MediaSource::seekable(stream)?;
     
    // From any `Read`:
    // let ms = MediaSource::unseekable(stream)?;
     
    Ok(())
}

```

--------------------------------

### Rust: Get EXIF Entry by Tag (ifd0)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_exif

Retrieves an EXIF entry value by its `ExifTag` from the main image file directory (ifd0). This method returns `None` if the tag is not found or if there was a parsing error.

```rust
/// Get entry value for the specified `tag` in ifd0 (the main image).
///
/// *Note*:
///
/// - The parsing error related to this tag won't be reported by this
///   method. Either this entry is not parsed successfully, or the tag does
///   not exist in the input data, this method will return None.
///
/// - If you want to handle parsing error, please consider to use
///   [`ExifIter`].
///
/// - If you have any custom defined tag which does not exist in
///   [`ExifTag`], you can always get the entry value by a raw tag code,
///   see [`Self::get_by_tag_code`].
///
///   ## Example
///
///   ```rust
///   use nom_exif::*;
///
///   fn main() -> Result<()> {
///       let mut parser = MediaParser::new();
///       
///       let ms = MediaSource::file_path("./testdata/exif.jpg")?;
///       let iter: ExifIter = parser.parse(ms)?;
///       let exif: Exif = iter.into();
///
///       assert_eq!(exif.get(ExifTag::Model).unwrap(), &"vivo X90 Pro+".into());
///       Ok(())
///   }
///   ```
pub fn get(&self, tag: ExifTag) -> Option<&EntryValue> {
    self.get_by_ifd_tag_code(0, tag.code())
}
```

--------------------------------

### Rewind IfdIter

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_iter

Resets the IfdIter to its starting position for re-iteration. It sets the index to 0 and adjusts the position to skip the initial two bytes which contain the entry number. This allows re-processing IFD entries.

```rust
pub fn rewind(&mut self) {
        self.index = 0;
        // Skip the first two bytes, which is the entry num
        self.pos = self.offset + 2;
    }
```

--------------------------------

### Rust: Parse QuickTime Metadata

Source: https://docs.rs/nom-exif/latest/src/nom_exif/mov

This snippet demonstrates the parsing of QuickTime metadata tags, including location, camera make, model, software version, creation date, duration, and dimensions. It utilizes a specific syntax for defining these tags.

```rust
544("com.apple.quicktime.location.ISO6709", Text("+22.5797+113.9380+028.396/"))
545("com.apple.quicktime.make", Text("Apple"))
546("com.apple.quicktime.model", Text("iPhone 15 Pro"))
547("com.apple.quicktime.software", Text("17.1"))
548("com.apple.quicktime.creationdate", Time(2023-11-02T19:58:34+08:00))
549("duration", U32(2795))
550("width", U32(1920))
551("height", U32(1440))
```

--------------------------------

### Test Buffer Acquisition, Sharing, and Pooling Logic

Source: https://docs.rs/nom-exif/latest/src/nom_exif/buffer

Tests the buffer management system's behavior for acquiring, releasing to share, and pooling buffers. It verifies the counts of acquired, shared, and pooled buffers throughout various operations, including scenarios where pooled buffers are limited. Dependencies include `Buffers::new`, `Buffers::acquire`, `Buffers::release_to_share`, `Buffers::release`, `Buffers::acquired`, `Buffers::shared`, and `Buffers::pooled`.

```rust
    #[test]
    fn buffers_test() {
        let mut bb = Buffers::new();
        assert_eq!(bb.acquired(), 0);
        assert_eq!(bb.pooled(), INIT_POOLED_BUF);
        assert_eq!(bb.shared(), 0);

        let mut bufs = Vec::with_capacity(NUM);
        for i in 1..=NUM {
            let buf = bb.acquire();
            assert_eq!(bb.acquired(), i);
            assert_eq!(bb.shared(), 0);
            assert_eq!(bb.pooled(), INIT_POOLED_BUF.saturating_sub(i));
            bufs.push(buf);
        }
        assert_eq!(bb.acquired(), NUM);
        assert_eq!(bb.shared(), 0);
        assert_eq!(bb.pooled(), 0);

        let mut shared = Vec::with_capacity(NUM);
        for i in 1..=NUM {
            let arc = bb.release_to_share(bufs.pop().unwrap());
            assert_eq!(bb.acquired(), NUM - i);
            assert_eq!(bb.shared(), i);
            assert_eq!(bb.pooled(), 0);
            shared.push(arc);
        }
        assert_eq!(bb.acquired(), NUM);
        assert_eq!(bb.shared(), NUM);
        assert_eq!(bb.pooled(), 0);

        for i in 1..=NUM {
            bb.release(bufs.pop().unwrap());
            assert_eq!(bb.acquired(), NUM - i);
            assert_eq!(bb.shared(), NUM);
            assert_eq!(bb.pooled(), min(i, MAX_POOLED_BUF));
        }
        assert_eq!(bb.acquired(), 0);
        assert_eq!(bb.shared(), NUM);
        assert_eq!(bb.pooled(), min(NUM, MAX_POOLED_BUF));

        for i in 1..=NUM {
            drop(shared.pop().unwrap());
            let buf = bb.acquire();
            let take_pooled = i <= MAX_POOLED_BUF;
            assert_eq!(bb.acquired(), i);
            assert_eq!(
                bb.shared(),
                if take_pooled {
                    NUM
                } else {
                    NUM + MAX_POOLED_BUF - i
                },
                "i: {i}"
            );
            assert_eq!(
                bb.pooled(),
                min(NUM, MAX_POOLED_BUF).saturating_sub(i),
                "i: {i}"
            );
            bufs.push(buf);
        }
        assert_eq!(bb.acquired(), NUM);
        assert_eq!(bb.shared(), NUM - 1);
        assert_eq!(bb.pooled(), 0);

        for i in 1..=NUM {
            bb.acquire();
            assert_eq!(bb.acquired(), NUM + i);
            assert_eq!(bb.shared(), NUM.saturating_sub(i).saturating_sub(1));
            assert_eq!(bb.pooled(), 0);
        }
        assert_eq!(bb.acquired(), 2 * NUM);
        assert_eq!(bb.shared(), 0);
        assert_eq!(bb.pooled(), 0);
    }

```

--------------------------------

### Working with EntryValue Variants in Rust

Source: https://context7.com/context7/rs_nom-exif/llms.txt

Explains how to handle the `EntryValue` enum in nom-exif, which represents various data types in metadata entries. It shows examples of extracting string, integer, rational, and time values.

```rust
use nom_exif::*

fn main() -> Result<()> {
    let mut parser = MediaParser::new();
    let ms = MediaSource::file_path("./testdata/exif.jpg")?;
    let iter: ExifIter = parser.parse(ms)?;
    let exif: Exif = iter.into();

    // String values
    if let Some(value) = exif.get(ExifTag::Make) {
        if let Some(s) = value.as_str() {
            println!("Text: {}", s);
        }
    }

    // Integer values
    if let Some(value) = exif.get(ExifTag::ImageWidth) {
        if let Some(w) = value.as_u32() {
            println!("U32: {}", w);
        }
    }

    // Rational values (fractions)
    if let Some(value) = exif.get(ExifTag::FNumber) {
        if let Some(rational) = value.as_urational() {
            let f_number = rational.as_float();
            println!("F-Number: f/{:.1}", f_number);
        }
    }

    if let Some(value) = exif.get(ExifTag::ExposureTime) {
        if let Some(rational) = value.as_urational() {
            println!("Exposure: 1/{}", (1.0 / rational.as_float()) as u32);
        }
    }

    // Time values
    if let Some(value) = exif.get(ExifTag::DateTimeOriginal) {
        println!("DateTime: {}", value);
    }

    // Array values
    if let Some(value) = exif.get(ExifTag::ISOSpeedRatings) {
        if let Some(iso) = value.as_u16() {
            println!("ISO: {}", iso);
        }
    }

    Ok(())
}
```

--------------------------------

### Unified Workflow for Various File Types in Rust

Source: https://docs.rs/nom-exif/latest/src/nom_exif/lib

Demonstrates how to use `MediaSource` and `MediaParser` to process different multimedia file types (images, videos, audio) with a unified API. It checks for Exif or track data and initiates parsing accordingly. This approach simplifies handling diverse file formats.

```rust
use nom_exif::*

fn main() -> Result<()>
{
    let mut parser = MediaParser::new();

    let files = [
        "./testdata/exif.heic",
        "./testdata/exif.jpg",
        "./testdata/tif.tif",
        "./testdata/meta.mov",
        "./testdata/meta.mp4",
        "./testdata/webm_480.webm",
        "./testdata/mkv_640x360.mkv",
        "./testdata/mka.mka",
        "./testdata/3gp_640x360.3gp"
    ];

    for f in files {
        let ms = MediaSource::file_path(f)?;

        if ms.has_exif() {
            // Parse the file as an Exif-compatible file
            let mut iter: ExifIter = parser.parse(ms)?;
            // ...
        } else if ms.has_track() {
            // Parse the file as a track
            let info: TrackInfo = parser.parse(ms)?;
            // ...
        }
    }

    Ok(())
}

```

--------------------------------

### Rust: Get Single EXIF Entry Value by Tag Code (Deprecated)

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_exif

This deprecated method retrieves an EXIF entry value using its raw tag code from ifd0. Prefer `Self::get_by_tag_code` for updated code.

```rust
/// Get entry value for the specified `tag` in ifd0 (the main image).
#[deprecated(since = "1.5.0", note = "please use [`Self::get_by_tag_code`] instead")]
pub fn get_value_by_tag_code(&self, tag: u16) -> crate::Result<Option<EntryValue>> {
    Ok(self.get_by_ifd_tag_code(0, tag).map(|x| x.to_owned()))
}
```

--------------------------------

### Check EXIF Identifier - Rust

Source: https://docs.rs/nom-exif/latest/src/nom_exif/exif/exif_exif

Checks if a given byte slice starts with the standard EXIF identifier ('Exif\0\0'). This function is useful for validating if a file contains EXIF data. It utilizes the 'nom' crate for byte pattern matching.

```rust
pub(crate) const EXIF_IDENT: &str = "Exif\0\0";

pub(crate) fn check_exif_header(data: &[u8]) -> Result<bool, nom::Err<nom::error::Error<&[u8]>>> {
    tag::<_, _, nom::error::Error<_>>(EXIF_IDENT)(data).map(|_| true)
}

pub(crate) fn check_exif_header2(i: &[u8]) -> IResult<&[u8], ()> {
    let (remain, _) = nom::sequence::tuple((
        nom::number::complete::be_u32,
        nom::bytes::complete::tag(EXIF_IDENT),
    ))(i)?;
    Ok((remain, ()))
}
```

--------------------------------

### Rust: Asynchronous Media Parser Initialization

Source: https://docs.rs/nom-exif/latest/src/nom_exif/lib

Initializes the asynchronous MediaParser for non-blocking media file processing. It leverages the AsyncMediaSource trait. This is useful for I/O-bound operations where responsiveness is crucial.

```Rust
pub use parser_async::{AsyncMediaParser, AsyncMediaSource};
```
Tokens:
Raw