XMPKit

https://docs.rs/xmpkit
Admin
XMPKit is a pure Rust implementation of Adobe's XMP (Extensible Metadata Platform) Toolkit for...
Tokens:259,368
Snippets:2,078
Trust Score:9.1
Update:5 months ago
Show doc for...
Tokens:
Raw
### XmpOptions Example Usage

Source: https://docs.rs/xmpkit/latest/xmpkit/files/handler/struct.XmpOptions.html

An example demonstrating how to use XmpOptions with the builder pattern to open an XmpFile for update in strict mode.

```APIDOC
## §Example
```
use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
// Open for update with strict mode
file.open_with("photo.jpg", XmpOptions::default().for_update().strict())?;
// ... modify metadata ...
file.try_close()?;
```
```

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

### Example Usage of XmpOptions

Source: https://docs.rs/xmpkit/latest/xmpkit/files/handler/struct.XmpOptions.html

Demonstrates opening an XMP file for update with strict mode enabled using XmpOptions.

```rust
use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
// Open for update with strict mode
file.open_with("photo.jpg", XmpOptions::default().for_update().strict())?;
// ... modify metadata ...
file.try_close()?;
```

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

### Create New XMP Metadata

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Initializes an empty XMP metadata object. Use this to start building XMP data from scratch.

```rust
pub fn new() -> Self {
    Self {
        root: new_root_node(StructureNode::new()),
        namespaces: NamespaceMap::new(),
        about_uri: None,
    }
}
```

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

### Create New XMP Parser

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/parser.rs.html

Instantiates a new `XmpParser` with an empty namespace map. This is the starting point for parsing XMP data.

```rust
pub fn new() -> Self {
        Self {
            namespaces: NamespaceMap::new(),
        }
    }
```

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

### Get Data Offset

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/riff/struct.RiffChunk.html

Retrieves the starting position of the chunk's data, immediately following the header.

```rust
pub fn data_offset(&self) -> u64
```

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

### Create a new SimpleNode

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/struct.SimpleNode.html

Use this function to initialize a new SimpleNode with a given string value. No setup is required.

```rust
pub fn new(value: impl Into<String>) -> Self>
```

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

### Get Default Registry Instance

Source: https://docs.rs/xmpkit/latest/xmpkit/files/registry/fn.default_registry.html

Use this function to access the global default handler registry. No setup or imports are required beyond the function itself.

```rust
pub fn default_registry() -> HandlerRegistry
```

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

### Get Built-in Namespace URIs - Rust

Source: https://docs.rs/xmpkit/latest/xmpkit/core/namespace/fn.get_builtin_namespace_uris.html

Call this function to retrieve a vector containing all the built-in namespace URIs supported by the xmpkit library. No setup is required.

```rust
pub fn get_builtin_namespace_uris() -> Vec<String>
```

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

### Example: Update XMP Metadata and Close File

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Demonstrates how to open a file for update, modify its XMP metadata, and then close it to write the changes to disk. Includes setting a 'CreatorTool' property.

```rust
use xmpkit::{XmpFile, XmpOptions, XmpMeta, XmpValue};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;

let mut meta = file.get_xmp().cloned().unwrap_or_else(XmpMeta::new);
meta.set_property(
    "http://ns.adobe.com/xap/1.0/",
    "CreatorTool",
    XmpValue::String("MyApp".to_string()),
)?;
file.put_xmp(meta);

// Write changes to disk
file.try_close()?;
# Ok(())
# }
```

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

### Serialize Simple Node

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/serializer.rs.html

Serializes a simple node, which contains a string value. It parses the path to get the prefix and property name, then writes the element start, text content, and element end to the writer. Qualifiers like `xml:lang` are added as attributes.

```rust
fn serialize_simple_node(
        &self,
        writer: &mut Writer<Cursor<Vec<u8>>>, 
        path: &str,
        node: &crate::core::node::SimpleNode,
    ) -> XmpResult<()> {
        let (prefix, prop_name) = self
            .parse_path(path)
            .ok_or_else(|| XmpError::BadXPath(format!("Invalid path format: {}", path)))?;

        let elem_name = format!("{}:{}", prefix, prop_name);
        let mut elem_start = BytesStart::new(&elem_name);

        // Add qualifiers as attributes (e.g., xml:lang)
        self.add_lang_qualifier_attributes(&Node::Simple(node.clone()), &mut elem_start);

        writer.write_event(Event::Start(elem_start))?;
        writer.write_event(Event::Text(BytesText::new(&node.value)))?;
        writer.write_event(Event::End(BytesEnd::new(&elem_name)))?;

        Ok(())
    }
```

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

### XmpOptions Initialization

Source: https://docs.rs/xmpkit/latest/xmpkit/files/handler/struct.XmpOptions.html

Provides methods for initializing XMP options.

```APIDOC
## type Init
The type for initializers.

## unsafe fn init(init: <T as Pointable>::Init) -> usize
Initializes a with the given initializer.
```

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

### Set and Get XMP Property

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Illustrates how to set a string property within XMP metadata and then retrieve it. Ensures the correct value is returned.

```rust
        let mut meta = XmpMeta::new();
        meta.set_property(
            "http://ns.adobe.com/xap/1.0/",
            "CreatorTool",
            XmpValue::String("TestApp".to_string()),
        )
        .unwrap();

        let value = meta.get_property("http://ns.adobe.com/xap/1.0/", "CreatorTool");
        assert_eq!(value, Some(XmpValue::String("TestApp".to_string())));
```

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

### Get TypeId of SimpleNode

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/struct.SimpleNode.html

Gets the TypeId of the SimpleNode. This is part of the blanket implementation of the Any trait.

```rust
fn type_id(&self) -> TypeId>
```

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

### Working with Files (Native Platforms) in Rust

Source: https://docs.rs/xmpkit/latest/src/xmpkit/lib.rs.html

Demonstrates how to open, read, modify, and save XMP metadata from files using XmpFile. Ensure the file path is correct and the file is accessible.

```rust
use xmpkit::{XmpFile, XmpMeta, XmpValue};
use xmpkit::core::namespace::ns;

# fn main() -> Result<(), Box<dyn std::error::Error>> {
// Open a file
let mut file = XmpFile::new();
file.open("image.jpg")?;

// Read XMP metadata
if let Some(meta) = file.get_xmp() {
    if let Some(creator) = meta.get_property(ns::XMP, "CreatorTool") {
        println!("Creator: {:?}", creator);
    }
}

// Modify metadata
if let Some(mut meta) = file.get_xmp().cloned() {
    meta.set_property(
        ns::XMP,
        "CreatorTool",
        XmpValue::String("MyApp".to_string()),
    )?;
    file.put_xmp(meta);
}

// Save changes
file.save("output.jpg")?;
# Ok(())
# }
```

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

### Create a New Handler Registry

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/registry.rs.html

Initializes a new HandlerRegistry and automatically registers all default handlers. This is the standard way to get a ready-to-use registry.

```rust
pub fn new() -> Self {
        let mut registry = Self {
            handlers: Vec::new(),
        };
        registry.register_defaults();
        registry
    }
```

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

### from_reader_with

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Opens an XMP file from a reader with specified options.

```APIDOC
## from_reader_with

### Description
Opens an XMP file from a reader with custom options, enabling advanced configurations like strict parsing or smart handler usage.

### Signature
`pub fn from_reader_with<R: Read + Seek>(&mut self, reader: R, options: XmpOptions) -> XmpResult<()>`

### Parameters
- **reader** (`R`): A type implementing `Read + Seek` that provides the file data.
- **options** (`XmpOptions`): Configuration options for opening the file.

### Returns
- `XmpResult<()>`: Ok(()) on success, or an XmpError on failure.

### Example
```rust,ignore
use std::io::Cursor;
use xmpkit::{XmpFile, XmpOptions};

let data: Vec<u8> = /* your file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader_with(cursor, XmpOptions::default().strict())?;
```
```

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

### Any for T

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Provides the `type_id` method to get the `TypeId` of an object.

```APIDOC
## fn type_id(&self) -> TypeId

Gets the `TypeId` of `self`.
```

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

### Write and Read XMP Metadata in PNG

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/png.rs.html

Demonstrates creating a minimal PNG, embedding XMP metadata, and then reading it back to verify integrity. Requires a PNG creation function and XMP metadata setup.

```rust
let png_data = create_minimal_png();
        let reader = Cursor::new(png_data);
        let mut writer = Cursor::new(Vec::new());

        let mut meta = XmpMeta::new();
        meta.set_property(ns::DC, "title", XmpValue::String("Test Image".to_string()))
            .unwrap();

        PngHandler::write_xmp(reader, &mut writer, &meta).unwrap();

        writer.set_position(0);
        let result = PngHandler::read_xmp(writer).unwrap();
        assert!(result.is_some());

        let read_meta = result.unwrap();
        let title_value = read_meta.get_property(ns::DC, "title");
        assert!(title_value.is_some());
        if let Some(XmpValue::String(title)) = title_value {
            assert_eq!(title, "Test Image");
        } else {
            panic!("Expected string value");
        }
```

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

### MpeghHandler::extensions

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/bmff/mpegh/struct.MpeghHandler.html

Gets the file extensions that this handler supports.

```APIDOC
## MpeghHandler::extensions

### Description
Get the file extensions this handler supports.

### Signature
```rust
fn extensions(&self) -> &'static [&'static str]
```

### Returns
A static slice of string slices, where each string slice is a supported file extension.
```

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

### Write and Verify XMP Metadata in PSD

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/psd.rs.html

Demonstrates creating XMP metadata, writing it to a PSD file, and then reading it back to verify the operation. Ensure the writer and reader are properly initialized and that the write operation is successful before attempting to read.

```rust
        // Create XMP metadata
        let mut meta = XmpMeta::new();
        meta.set_property(
            "http://purl.org/dc/elements/1.1/",
            "creator",
            "Test Author".into(),
        )
        .unwrap();

        // Write XMP
        let result = handler.write_xmp(&mut reader, &mut writer, &meta);
        assert!(result.is_ok());

        // Verify we can read it back
        let written_data = writer.into_inner();
        let mut read_cursor = Cursor::new(written_data);
        let read_result = handler.read_xmp(&mut read_cursor, &XmpOptions::default());
        assert!(read_result.is_ok());
        assert!(read_result.unwrap().is_some());
```

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

### XmpMeta::get_array_size

Source: https://docs.rs/xmpkit/latest/xmpkit/core/metadata/struct.XmpMeta.html

Gets the number of items in an array property.

```APIDOC
## XmpMeta::get_array_size

### Description
Get the size of an array property

### Method
`pub fn get_array_size(&self, namespace: &str, path: &str) -> Option<usize>`

### Parameters
#### Path Parameters
* **namespace** (str) - The namespace URI or prefix
* **path** (str) - The array property path
```

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

### XmpParser::new

Source: https://docs.rs/xmpkit/latest/xmpkit/core/parser/struct.XmpParser.html

Creates a new instance of the XMP parser.

```APIDOC
## XmpParser::new

### Description
Create a new XMP parser.

### Method
`new()`

### Returns
- `Self`: A new instance of `XmpParser`.
```

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

### XmpOptions Configuration Methods

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/handler.rs.html

Provides methods to configure XMP file operation options. Use these to specify read-only, update, strict, or smart handler preferences.

```rust
impl XmpOptions {
    /// Open for read-only access (default).
    pub fn for_read(mut self) -> Self {
        self.for_update = false;
        self
    }

    /// Open for reading and writing.
    ///
    /// Files opened for update are written to only when closing.
    pub fn for_update(mut self) -> Self {
        self.for_update = true;
        self
    }

    /// Only the XMP is wanted.
    ///
    /// This allows space/time optimizations by skipping reconciliation
    /// with native metadata formats (e.g., QuickTime metadata in MPEG4).
    pub fn only_xmp(mut self) -> Self {
        self.only_xmp = true;
        self
    }

    /// Force use of the given handler (format).
    ///
    /// Do not even verify the format.
    pub fn force_given_handler(mut self) -> Self {
        self.force_given_handler = true;
        self
    }

    /// Be strict about only attempting to use the designated file handler.
    ///
    /// Do not fall back to other handlers.
    pub fn strict(mut self) -> Self {
        self.strict = true;
        self
    }

    /// Require the use of a smart handler.
    ///
    /// Do not fall back to packet scanning.
    pub fn use_smart_handler(mut self) -> Self {
        self.use_smart_handler = true;
        self
    }

    /// Force packet scanning.
    ///
    /// Do not use a smart handler.
    pub fn use_packet_scanning(mut self) -> Self {
        self.use_packet_scanning = true;
        self
    }

    /// Only packet scan files "known" to need scanning.
    pub fn limited_scanning(mut self) -> Self {
        self.limited_scanning = true;
        self
    }
}
```

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

### XmpMeta::get_array_size

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Gets the number of items in an array property.

```APIDOC
## XmpMeta::get_array_size

### Description
Retrieves the number of items currently in a specified array property.

### Method
`get_array_size(&self, namespace: &str, path: &str) -> Option<usize>`

### Parameters
- **namespace** (&str) - The namespace of the array property.
- **path** (&str) - The path (name) of the array property.

### Response
- **Option<usize>** - Some(usize) containing the size of the array if it exists and is an array, None otherwise.
```

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

### from_bytes_with

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Opens an XMP file from a byte slice with specified options.

```APIDOC
## from_bytes_with

### Description
Opens an XMP file from a byte slice with custom options, allowing fine-grained control over the parsing process.

### Signature
`pub fn from_bytes_with(&mut self, data: &[u8], options: XmpOptions) -> XmpResult<()>`

### Parameters
- **data** (`&[u8]`): A slice of bytes representing the file content.
- **options** (`XmpOptions`): Configuration options for opening the file, such as enabling packet scanning.

### Returns
- `XmpResult<()>`: Ok(()) on success, or an XmpError on failure.

### Example
```rust,ignore
use xmpkit::{XmpFile, XmpOptions};

let data: &[u8] = /* your file data */;
let mut file = XmpFile::new();
file.from_bytes_with(data, XmpOptions::default().use_packet_scanning())?;
```
```

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

### get_global_namespace_uri

Source: https://docs.rs/xmpkit/latest/xmpkit/core/namespace/fn.get_global_namespace_uri.html

Get the URI for a namespace prefix from global registry.

```APIDOC
## Function get_global_namespace_uri

### Description
Get the URI for a namespace prefix from global registry.

### Signature
```rust
pub fn get_global_namespace_uri(prefix: &str) -> Option<String>
```

### Parameters
* `prefix` (*str*) - The namespace prefix to look up.

### Returns
* `Option<String>` - An `Option` containing the URI string if the prefix is found, otherwise `None`.
```

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

### PdfHandler::extensions

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/pdf/struct.PdfHandler.html

Gets the file extensions associated with the PDF format.

```APIDOC
## PdfHandler::extensions

### Description
Get the file extensions this handler supports.

### Method
`fn extensions(&self) -> &'static [&'static str]`

### Returns
- `&'static [&'static str]` - A static slice of supported file extensions (e.g., `["pdf"]`).
```

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

### XmpFile::new

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Creates a new, empty `XmpFile` instance. Use `open_file()` or `from_*()` methods to load metadata.

```APIDOC
## XmpFile::new

### Description
Creates a new empty XmpFile. Use `open_file()` or `from_*()` methods to load metadata from a file.

### Signature
```rust
pub fn new() -> Self
```
```

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

### PdfHandler::format_name

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/pdf/struct.PdfHandler.html

Gets the name of the file format supported by this handler.

```APIDOC
## PdfHandler::format_name

### Description
Get the name of the file format this handler supports.

### Method
`fn format_name(&self) -> &'static str`

### Returns
- `&'static str` - The name of the file format (e.g., "PDF").
```

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

### Create and Parse XmpMeta

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Demonstrates creating a new XmpMeta instance and parsing XML content into an XmpMeta object. Also shows usage of the `FromStr` trait for parsing.

```rust
    let meta = XmpMeta::new();
    assert!(meta.about_uri().is_none());
```

```rust
        let xml = r#"<?xpacket begin="" id="W5M0MpCehiHzreSzNTczkc9d"?>
<rdf:RDF xmlns:rdf="http://www.w3.org/1999/02/22-rdf-syntax-ns#"
         xmlns:xmp="http://ns.adobe.com/xap/1.0/">
 <rdf:Description rdf:about=""
                   xmp:CreatorTool="MyApp"/>
</rdf:RDF>
<?xpacket end="w"?>"#;

        let result = XmpMeta::parse(xml);
        assert!(result.is_ok());

        // Test FromStr trait
        let result2 = xml.parse::<XmpMeta>();
        assert!(result2.is_ok());
```

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

### Working with Files (Native Platforms)

Source: https://docs.rs/xmpkit

Use this snippet to open, read, modify, and save XMP metadata directly from files on native platforms. Ensure the file path is correct and the file is accessible.

```rust
use xmpkit::{XmpFile, XmpMeta, XmpValue};
use xmpkit::core::namespace::ns;

// Open a file
let mut file = XmpFile::new();
file.open("image.jpg")?;

// Read XMP metadata
if let Some(meta) = file.get_xmp() {
    if let Some(creator) = meta.get_property(ns::XMP, "CreatorTool") {
        println!("Creator: {:?}", creator);
    }
}

// Modify metadata
if let Some(mut meta) = file.get_xmp().cloned() {
    meta.set_property(
        ns::XMP,
        "CreatorTool",
        XmpValue::String("MyApp".to_string()),
    )?;
    file.put_xmp(meta);
}

// Save changes
file.save("output.jpg")?;
```

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

### MpeghHandler::format_name

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/bmff/mpegh/struct.MpeghHandler.html

Gets the name of the file format that this handler supports.

```APIDOC
## MpeghHandler::format_name

### Description
Get the name of the file format this handler supports.

### Signature
```rust
fn format_name(&self) -> &'static str
```

### Returns
A static string slice representing the name of the supported file format.
```

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

### XmpFile::open_with

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file from a given path with specified options. This method is intended for native platforms only.

```APIDOC
## XmpFile::open_with

### Description
Open a file from a path with options (native platforms only)

### Platform Support
- Native platforms (iOS, Android, macOS, Windows)
- Wasm: Not supported (use `from_bytes()` or `from_reader()` instead)

### Parameters
#### Path Parameters
- **path** (P: AsRef<Path>): The path to the file to open.
- **options** (XmpOptions): The options to use when opening the file.

### Returns
- XmpResult<()>: Ok(()) on success, or an error if the file could not be opened or processed.

### Example
```rust
use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;
```
```

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

### Get the about URI

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Retrieves the 'about' URI associated with the XMP metadata.

```APIDOC
## about_uri

### Description
Gets the 'about' URI associated with the XMP metadata.

### Returns
An `Option<&str>` containing the 'about' URI if set, otherwise `None`.
```

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

### get_global_namespace_prefix

Source: https://docs.rs/xmpkit/latest/xmpkit/core/namespace/index.html

Gets the prefix for a given namespace URI from the global registry.

```APIDOC
## get_global_namespace_prefix

### Description
Get the prefix for a namespace URI from global registry.

### Function Signature
`fn get_global_namespace_prefix(uri: &str) -> Option<String>`

### Parameters
#### Path Parameters
- **uri** (str) - Required - The namespace URI to look up.

### Returns
An `Option<String>` containing the namespace prefix if found, otherwise `None`.
```

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

### HandlerRegistry::new

Source: https://docs.rs/xmpkit/latest/xmpkit/files/registry/struct.HandlerRegistry.html

Creates a new instance of HandlerRegistry, pre-populated with default file format handlers.

```APIDOC
## HandlerRegistry::new

### Description
Create a new handler registry with default handlers registered.

### Method
`pub fn new() -> Self`

### Returns
A new `HandlerRegistry` instance.
```

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

### Get All Field Names

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/struct.StructureNode.html

Returns an iterator over the names of all fields present in the StructureNode.

```rust
pub fn field_names(&self) -> impl Iterator<Item = &String>
```

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

### Initialize XmpFile

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Creates a new instance of XmpFile. This is the default way to initialize the struct.

```rust
impl Default for XmpFile {
    fn default() -> Self {
        Self::new()
    }
}
```

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

### Node Accessor Methods

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/enum.Node.html

Methods to get references to the inner node types.

```APIDOC
#### pub fn as_simple(&self) -> Option<&SimpleNode>
Get the simple node, if this is a simple node

#### pub fn as_array(&self) -> Option<&ArrayNode>
Get the array node, if this is an array node

#### pub fn as_structure(&self) -> Option<&StructureNode>
Get the structure node, if this is a structure node
```

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

### Create Minimal WAV File

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/riff/wav.rs.html

Constructs a basic, valid WAV file with essential RIFF and fmt chunks. This is useful for testing or as a starting point for more complex WAV files.

```rust
fn create_minimal_wav() -> Vec<u8> {
        let mut wav = Vec::new();

        // RIFF header
        wav.extend_from_slice(b"RIFF");

        // fmt chunk (minimal: 16 bytes for PCM)
        let fmt_data: Vec<u8> = vec![
            0x01, 0x00, // Audio format: PCM
            0x01, 0x00, // Channels: 1 (mono)
            0x44, 0xAC, 0x00, 0x00, // Sample rate: 44100
            0x88, 0x58, 0x01, 0x00, // Byte rate: 88200
            0x02, 0x00, // Block align: 2
            0x10, 0x00, // Bits per sample: 16
        ];

        // data chunk (empty for testing)
        let data_chunk: Vec<u8> = vec![];

        // Calculate file size
        let file_size = 4 + 8 + fmt_data.len() + 8 + data_chunk.len();
        wav.extend_from_slice(&(file_size as u32).to_le_bytes());

        // WAVE signature
        wav.extend_from_slice(WAVE_SIGNATURE);

        // fmt chunk
        wav.extend_from_slice(FMT_CHUNK_ID);
        wav.extend_from_slice(&(fmt_data.len() as u32).to_le_bytes());
        wav.extend_from_slice(&fmt_data);

        // data chunk
        wav.extend_from_slice(DATA_CHUNK_ID);
        wav.extend_from_slice(&(data_chunk.len() as u32).to_le_bytes());

        wav
    }
```

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

### Get a property value

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Retrieves the value of a specific property from the XMP metadata.

```APIDOC
## get_property

### Description
Gets a property value from the XMP metadata.

### Arguments
* `namespace` - The namespace URI or prefix of the property.
* `path` - The property path (e.g., "CreatorTool" or "creator[1]").

### Returns
An `Option<XmpValue>` containing the property's value if found, or `None` if the property does not exist or is not a simple value.
```

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

### data_offset

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/riff/struct.RiffChunk.html

Retrieves the starting offset of the chunk's data, located after the header.

```APIDOC
### pub fn data_offset(&self) -> u64

Get the data offset (after the header)
```

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

### Open XMP from Reader

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

This is the most flexible method for opening XMP files, accepting any type that implements `Read + Seek`. Use this when you have a custom reader or need maximum flexibility.

```rust
use std::io::Cursor;
use xmpkit::XmpFile;

let data: Vec<u8> = /* your JPEG file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader(cursor)?;
```

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

### read_all_chunks

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/riff/mod.rs.html

Reads all RIFF chunks in the file, starting after the main RIFF header.

```APIDOC
## read_all_chunks<R: Read + Seek>(reader: &mut R) -> XmpResult<Vec<RiffChunk>>

### Description
Reads and returns a vector of all `RiffChunk` structures found in the file, starting from the position after the main RIFF header.

### Parameters
- **reader** (&mut R) - A mutable reference to a type implementing `Read` and `Seek`.

### Returns
XmpResult<Vec<RiffChunk>> - Ok containing a vector of `RiffChunk` if successful, otherwise an XmpError.
```

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

### Get Last Component

Source: https://docs.rs/xmpkit/latest/xmpkit/core/xpath/struct.PathComponents.html

Retrieves a reference to the last component in the path, if the path is not empty.

```rust
pub fn last(&self) -> Option<&PathComponent>
```

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

### Test Writing and Reading XMP Metadata in MP4

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/bmff/mpeg4.rs.html

Demonstrates the process of creating XMP metadata, writing it into an MP4 file using `Mpeg4Handler::write_xmp`, and then reading it back to verify its integrity.

```rust
#[test]
    fn test_write_xmp() {
        // Create minimal MP4
        let mp4_data = create_minimal_mp4();
        let reader = Cursor::new(mp4_data);
        let mut writer = Cursor::new(Vec::new());

        // Create XMP metadata
        let mut meta = XmpMeta::new();
        meta.set_property(ns::DC, "title", XmpValue::String("Test Video".to_string()))
            .unwrap();

        // Write XMP
        Mpeg4Handler::write_xmp(reader, &mut writer, &meta).unwrap();

        // Read back XMP
        writer.set_position(0);
        let result = Mpeg4Handler::read_xmp(writer, &XmpOptions::default()).unwrap();
        assert!(result.is_some());

        let read_meta = result.unwrap();
        let title_value = read_meta.get_property(ns::DC, "title");
        assert!(title_value.is_some());
        if let Some(XmpValue::String(title)) = title_value {
            assert_eq!(title, "Test Video");
        } else {
            panic!("Expected string value");
        }
    }
```

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

### XmpFile::open_with

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Opens a file from a given path with specified options. This method is intended for native platforms and is not supported on Wasm.

```APIDOC
## XmpFile::open_with

### Description
Open a file from a path with options (native platforms only).

# Platform Support

- Native platforms (iOS, Android, macOS, Windows)
- Wasm: Not supported (use `from_bytes()` or `from_reader()` instead)

### Method
```rust
#[cfg(not(target_arch = "wasm32"))]
pub fn open_with<P: AsRef<std::path::Path>>(
    &mut self,
    path: P,
    options: XmpOptions,
) -> XmpResult<()>
```

### Parameters

- **path**: `P: AsRef<std::path::Path>` - The path to the file to open.
- **options**: `XmpOptions` - The options to use when opening the file.

### Returns

- `XmpResult<()>`: Returns `Ok(())` on success, or an `XmpError` on failure.

### Example

```rust,no_run
use xmpkit::{XmpFile, XmpOptions};

# fn main() -> Result<(), Box<dyn std::error::Error>> {
let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;
# Ok(())
# }
```
```

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

### Get First Component Name

Source: https://docs.rs/xmpkit/latest/xmpkit/core/xpath/struct.PathComponents.html

Retrieves the name of the first component in the path, if it exists.

```rust
pub fn first_name(&self) -> Option<&str>
```

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

### Open XMP from Bytes with Options

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Use this method to open an XMP file from a byte slice with specific options. It allows for forcing packet scanning or requiring a smart handler.

```rust
use xmpkit::{XmpFile, XmpOptions};

let data: &[u8] = /* your file data */;
let mut file = XmpFile::new();
file.from_bytes_with(data, XmpOptions::default().use_packet_scanning())?;
```

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

### Get MpeghHandler Supported Extensions

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/bmff/mpegh/struct.MpeghHandler.html

Retrieves a static slice of file extensions that this handler supports.

```rust
fn extensions(&self) -> &'static [&'static str]
```

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

### Mutable Node Accessor Methods

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/enum.Node.html

Methods to get mutable references to the inner node types.

```APIDOC
#### pub fn as_simple_mut(&mut self) -> Option<&mut SimpleNode>
Get a mutable reference to the simple node, if this is a simple node

#### pub fn as_array_mut(&mut self) -> Option<&mut ArrayNode>
Get a mutable reference to the array node, if this is an array node

#### pub fn as_structure_mut(&mut self) -> Option<&mut StructureNode>
Get a mutable reference to the structure node, if this is a structure node
```

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

### Test Writing and Reading XMP in WAV

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/riff/wav.rs.html

Tests the complete cycle of writing XMP metadata to a WAV file and then reading it back.

```rust
#[test]
    fn test_write_and_read_xmp() {
        let handler = WavHandler;
        let wav_data = create_minimal_wav();
        let mut reader = Cursor::new(wav_data);
        let mut writer = Cursor::new(Vec::new());

        let mut meta = XmpMeta::new();
        meta.set_property(ns::DC, "title", XmpValue::String("Test WAV".to_string()))
            .unwrap();

        handler.write_xmp(&mut reader, &mut writer, &meta).unwrap();

        writer.set_position(0);
        let result = handler
            .read_xmp(&mut writer, &XmpOptions::default().only_xmp())
            .unwrap();
        assert!(result.is_some());
    }
```

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

### XmpMeta::new

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Creates a new, empty XMP metadata object.

```APIDOC
## XmpMeta::new

### Description
Create a new empty XMP metadata object

### Method
`XmpMeta::new()`

### Returns
A new `XmpMeta` instance with an empty root node, empty namespace map, and no about URI.
```

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

### Get all registered namespaces

Source: https://docs.rs/xmpkit/latest/xmpkit/core/namespace/struct.NamespaceMap.html

Retrieves all currently registered namespaces as a vector of (URI, prefix) tuples.

```rust
pub fn get_all_namespaces(&self) -> Vec<(String, String)>
```

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

### XmpFile::open

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file from a path using default options. This method is for native platforms only.

```APIDOC
## XmpFile::open

### Description
Open a file from a path (native platforms only)

### Platform Support
- Native platforms (iOS, Android, macOS, Windows)
- Wasm: Not supported (use `from_bytes()` or `from_reader()` instead)

### Parameters
#### Path Parameters
- **path** (P: AsRef<Path>): The path to the file to open.

### Returns
- XmpResult<()>: Ok(()) on success, or an error if the file could not be opened.

### Example
```rust
use xmpkit::XmpFile;

let mut file = XmpFile::new();
file.open("image.jpg")?;
```
```

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

### Get Output type for Same trait

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/struct.SimpleNode.html

Specifies that the Output type for the Same trait is Self. This is a blanket implementation.

```rust
type Output = T>
```

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

### Open XMP from Reader with Options

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Use this method to open an XMP file from a reader with specific options. It's useful when you need to control how the file is read, such as enforcing strict mode.

```rust
use std::io::Cursor;
use xmpkit::{XmpFile, XmpOptions};

let data: Vec<u8> = /* your file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader_with(cursor, XmpOptions::default().strict())?;
```

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

### Get all field names from StructureNode

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/node.rs.html

Returns an iterator over the names of all fields currently stored in the StructureNode.

```rust
pub fn field_names(&self) -> impl Iterator<Item = &String> {
        self.fields.keys()
    }
```

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

### Get the full path of a Qualifier

Source: https://docs.rs/xmpkit/latest/xmpkit/types/qualifier/struct.Qualifier.html

Retrieves the combined namespace and name of the qualifier in the format 'namespace:name'.

```rust
pub fn path(&self) -> String
```

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

### Node Creation Methods

Source: https://docs.rs/xmpkit/latest/xmpkit/core/node/enum.Node.html

Methods for creating new Node instances.

```APIDOC
## Implementations
### impl Node
#### pub fn simple(value: impl Into<String>) -> Self
Create a new simple node

#### pub fn array(array_type: ArrayType) -> Self
Create a new array node

#### pub fn structure() -> Self
Create a new structure node
```

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

### Unwrap Error Value

Source: https://docs.rs/xmpkit/latest/xmpkit/core/error/type.XmpResult.html

Use `unwrap_err` to get the contained `Err` value. Panics if the result is `Ok`.

```rust
let x: Result<u32, &str> = Ok(2);
x.unwrap_err(); // panics with `2`
```

```rust
let x: Result<u32, &str> = Err("emergency failure");
assert_eq!(x.unwrap_err(), "emergency failure");
```

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

### Open File for Update (Native Platforms)

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file at the specified path for updating XMP metadata. This method is only supported on native platforms.

```rust
use xmpkit::{XmpFile, XmpOptions};

let mut file = XmpFile::new();
file.open_with("image.jpg", XmpOptions::default().for_update())?;
```

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

### Create a new XMP serializer

Source: https://docs.rs/xmpkit/latest/xmpkit/core/serializer/struct.XmpSerializer.html

Use this method to instantiate a new XMP serializer with default settings.

```rust
pub fn new() -> Self
```

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

### Unwrap Ok Value

Source: https://docs.rs/xmpkit/latest/xmpkit/core/error/type.XmpResult.html

Use `unwrap` to get the contained `Ok` value. Panics if the result is `Err`.

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

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

### XmpFile::from_reader_with

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file from a reader with specified options. Supports all platforms, including Wasm.

```APIDOC
## XmpFile::from_reader_with

### Description
Open a file from a reader with options (all platforms, including Wasm)
This method allows you to specify opening options when reading from a reader.

### Platform Support
- All platforms, including Wasm.

### Parameters
#### Path Parameters
- **reader** (R: Read + Seek): A type that implements the `Read` and `Seek` traits.
- **options** (XmpOptions): The options to use when opening the file.

### Returns
- XmpResult<()>: Ok(()) on success, or an error if the reader could not be processed with the given options.

### Example
```rust
use std::io::Cursor;
use xmpkit::{XmpFile, XmpOptions};

let data: Vec<u8> = /* your file data */;
let cursor = Cursor::new(data);
let mut file = XmpFile::new();
file.from_reader_with(cursor, XmpOptions::default().strict())?;
```
```

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

### Get MpeghHandler Format Name

Source: https://docs.rs/xmpkit/latest/xmpkit/files/formats/bmff/mpegh/struct.MpeghHandler.html

Retrieves the static string name of the file format supported by this handler.

```rust
fn format_name(&self) -> &'static str
```

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

### Test Same URI and Prefix Registration

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/namespace.rs.html

Verifies that registering a namespace with the exact same URI and prefix as an existing one succeeds without error.

```rust
#[test]
fn test_namespace_map_same_uri_prefix() {
    let mut map = NamespaceMap::new();
    assert!(map.register("http://example.com/ns", "ex").is_ok());
    // Registering again with same URI and prefix should succeed
    assert!(map.register("http://example.com/ns", "ex").is_ok());
}
```

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

### Get Array Size

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/metadata/mod.rs.html

Determines the number of items in a specified array property within the XMP metadata.

```APIDOC
## get_array_size

### Description
Gets the size of an array property.

### Arguments
- `namespace` (&str) - The namespace URI or prefix.
- `path` (&str) - The array property path.

### Returns
- `Option<usize>` - The number of items in the array, or `None` if the property is not an array or not found.
```

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

### Create Minimal PDF for Testing

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/pdf.rs.html

Generates a basic, valid PDF document structure using lopdf. This is useful for setting up test environments where a PDF file is required but its content is not critical.

```rust
fn create_minimal_pdf() -> Vec<u8> {
        let mut doc = Document::with_version("1.4");

        // Create a minimal page
        let pages_id = doc.new_object_id();
        let page_id = doc.new_object_id();

        let page = dictionary! {
            "Type" => "Page",
            "Parent" => Object::Reference(pages_id),
            "MediaBox" => vec![0.into(), 0.into(), 612.into(), 792.into()],
        };
        doc.objects.insert(page_id, Object::Dictionary(page));

        let pages = dictionary! {
            "Type" => "Pages",
            "Kids" => vec![Object::Reference(page_id)],
            "Count" => 1,
        };
        doc.objects.insert(pages_id, Object::Dictionary(pages));

        // Create catalog
        let catalog_id = doc.new_object_id();
        let catalog = dictionary! {
            "Type" => "Catalog",
            "Pages" => Object::Reference(pages_id),
        };
        doc.objects.insert(catalog_id, Object::Dictionary(catalog));

        // Set trailer
        doc.trailer.set("Root", Object::Reference(catalog_id));

        let mut buffer = Vec::new();
        doc.save_to(&mut buffer).unwrap();
        buffer
    }
```

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

### Test Put and Get XMP Metadata

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Tests the functionality of putting XMP metadata into an XmpFile and then retrieving it.

```rust
let mut file = XmpFile::new();
let meta = XmpMeta::new();
file.put_xmp(meta);
assert!(file.get_xmp().is_some());
```

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

### Get PDF Format Information

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/pdf.rs.html

Retrieves the format name and supported file extensions for the PDF handler.

```rust
let handler = PdfHandler;
assert_eq!(handler.format_name(), "PDF");
assert_eq!(handler.extensions(), &["pdf"]);
```

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

### Test Node Creation

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/node.rs.html

Shows how to create different types of nodes: simple, array, and structure nodes.

```rust
let simple = Node::simple("test");
assert!(simple.is_simple());

let array = Node::array(ArrayType::Ordered);
assert!(array.is_array());

let structure = Node::structure();
assert!(structure.is_structure());
```

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

### open

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Opens a file from a given path. This method is available on native platforms but not on Wasm.

```APIDOC
## open

### Description
Opens a file from a given path. This method is available on native platforms but not on Wasm. Use `from_bytes()` or `from_reader()` for Wasm environments.

### Platform Support

- Native platforms (iOS, Android, macOS, Windows)
- Wasm: Not supported

### Signature
`#[cfg(not(target_arch = "wasm32"))]
pub fn open<P: AsRef<std::path::Path>>(&mut self, path: P) -> XmpResult<()>`

### Parameters
- **path** (`P: AsRef<std::path::Path>`) - The path to the file to open.

### Returns
- `XmpResult<()>` - Returns `Ok(())` on success or an `Err` if the file cannot be opened or read.
```

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

### Get Built-in Namespace URIs

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/namespace.rs.html

Returns a vector containing the URIs of all namespaces that are built into the XMP specification.

```APIDOC
## get_builtin_namespace_uris

### Description
Retrieves a list of all built-in XMP namespace URIs.

### Signature
`pub fn get_builtin_namespace_uris() -> Vec<String>`

### Returns
*   `Vec<String>` - A vector of strings, each representing a built-in namespace URI.
```

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

### Get Built-in Namespace URIs

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/namespace.rs.html

Returns a vector containing the URIs of all namespaces that are built into the XMPKit library.

```rust
pub fn get_builtin_namespace_uris() -> Vec<String> {
    vec![
        ns::XMP.to_string(),
        ns::DC.to_string(),
        ns::EXIF.to_string(),
        ns::EXIF_AUX.to_string(),
        ns::IPTC_CORE.to_string(),
        ns::IPTC_EXT.to_string(),
        ns::PHOTOSHOP.to_string(),
        ns::CAMERA_RAW.to_string(),
        ns::XMP_RIGHTS.to_string(),
        ns::XMP_MM.to_string(),
        ns::XMP_BJ.to_string(),
        ns::TIFF.to_string(),
        ns::PDF.to_string(),
        ns::PDFX.to_string(),
        ns::PDFA.to_string(),
        ns::XMP_DM.to_string(),
        ns::XMP_PAGED.to_string(),
        ns::XMP_GRAPHICS.to_string(),
        ns::XMP_IMAGE.to_string(),
        ns::RDF.to_string(),
        ns::XML.to_string(),
    ]
}
```

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

### Supported File Formats

Source: https://docs.rs/xmpkit/latest/index.html

List of file formats supported by the XMP Kit, including their extensions and read/write capabilities.

```APIDOC
## Supported File Formats

| Format | Extensions | Read | Write |
|---|---|---|---|
| JPEG | .jpg, .jpeg | Yes | Yes |
| PNG | .png | Yes | Yes |
| TIFF | .tif, .tiff | Yes | Yes |
| MP3 | .mp3 | Yes | Yes |
| GIF | .gif | Yes | Yes |
| MPEG4 | .mp4, .m4a, .m4v, .mov | Yes | Yes |
```

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

### Open File from Bytes (All Platforms)

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens an XMP file from a byte slice. This is the recommended method for Wasm environments.

```rust
use xmpkit::XmpFile;

let jpeg_data: &[u8] = /* your JPEG file data */;
let mut file = XmpFile::new();
file.from_bytes(jpeg_data)?;
```

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

### Get a field by name from StructureNode

Source: https://docs.rs/xmpkit/latest/src/xmpkit/core/node.rs.html

Retrieves an immutable reference to a field within a StructureNode using its name.

```rust
pub fn get_field(&self, name: &str) -> Option<&Node> {
        self.fields.get(name)
    }
```

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

### XmpFile::from_bytes_with

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file from a byte slice with specified options. Supports all platforms, including Wasm.

```APIDOC
## XmpFile::from_bytes_with

### Description
Open a file from bytes with options (all platforms, including Wasm)
This method allows you to specify opening options, such as forcing packet scanning or requiring a smart handler.

### Platform Support
- All platforms, including Wasm.

### Parameters
#### Path Parameters
- **data** ( &[u8]): A slice of bytes representing the file content.
- **options** (XmpOptions): The options to use when opening the file.

### Returns
- XmpResult<()>: Ok(()) on success, or an error if the data could not be processed with the given options.

### Example
```rust
use xmpkit::{XmpFile, XmpOptions};

let data: &[u8] = /* your file data */;
let mut file = XmpFile::new();
file.from_bytes_with(data, XmpOptions::default().use_packet_scanning())?;
```
```

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

### is_bmff

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/formats/bmff/mod.rs.html

Checks if the provided reader is positioned at the start of a valid BMFF file by examining the 'ftyp' box.

```APIDOC
## is_bmff

### Description
Checks if the current position in the reader starts with a valid BMFF 'ftyp' box.

### Signature
```rust
pub fn is_bmff<R: Read + Seek>(reader: &mut R) -> std::io::Result<bool>
```

### Parameters
* `reader`: A mutable reference to a type implementing `Read` and `Seek` traits.
```

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

### Get XmpValue as Boolean

Source: https://docs.rs/xmpkit/latest/xmpkit/types/value/enum.XmpValue.html

Safely retrieves the value as a boolean if the XmpValue is of the Boolean variant. Returns None otherwise.

```rust
pub fn as_bool(&self) -> Option<bool>
```

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

### Open File (Native Platforms)

Source: https://docs.rs/xmpkit/latest/xmpkit/files/file/struct.XmpFile.html

Opens a file at the specified path. This method is only supported on native platforms.

```rust
use xmpkit::XmpFile;

let mut file = XmpFile::new();
file.open("image.jpg")?;
```

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

### Test XmpFile Initialization

Source: https://docs.rs/xmpkit/latest/src/xmpkit/files/file.rs.html

Verifies that a newly created XmpFile instance has no XMP metadata.

```rust
let file = XmpFile::new();
assert!(file.get_xmp().is_none());
```
Tokens:
Raw