Lofty

Lofty provides two distinct categories of benchmarks to measure performance:

1. File parsing: Measures the time taken to parse various supported file formats using representative assets. These assets use the format's "primary tag" type and include fields such as Title, Artist, Album, Date, Track number, Genre, Picture (Front cover), and Encoder.
2. Tag creation: Measures the time taken to create tags and dump them to a writer. Note that this category does not include the time required to write the tags to a physical file.

To allow conversion between your concrete tag and the generic Tag type, you must define how your format's string keys map to Lofty's ItemKey enum. Use the gen_map! macro to create a mapping, then register it using the gen_item_keys! macro in src/tag/item.rs.

// 1. Define the mapping
gen_map!(
    FOO_MAP;

    "TITLE" => TrackTitle,
    "ARIST" => TrackArtist,
    "ALBUM" => AlbumTitle,
);

// 2. Register the map in gen_item_keys!
gen_item_keys!(
    MAPS => [
        // ...
        [TagType::Foo, FOO_MAP]
    ];
    // ...
);

Define your concrete tag struct in src/your_tag/tag/mod.rs. Use the #[tag] attribute macro from lofty_attr to specify the tag's description and supported FileTypes. This macro automatically generates SUPPORTED_FORMATS and READ_ONLY_FORMATS constants and user-facing documentation.

To specify that a format is read-only (meaning the tag can be read or removed, but not written as a new tag), use the read_only(FileType) syntax within supported_formats.

use lofty_attr::tag;

// Standard support
#[tag(description = "A Foo tag", supported_formats(Foo))]
pub struct FooTag {
    items: Vec<(String, String)>
}

// Support with read-only constraints
#[tag(description = "A Foo tag", supported_formats(Foo, read_only(Mpeg)))]
pub struct FooTag {
    items: Vec<(String, String)>
}

When adding a new tag format, the directory structure depends on whether the tag is specific to one audio format or generic across multiple formats.

1. Format-specific tags: If the tag is only used by a specific audio format (e.g., the 'Foo' format), place the definition in a subdirectory of that format's directory.
2. Generic tags: If the tag is supported by multiple audio formats (e.g., ID3), define it in its own folder directly inside src/.

Every tag implementation requires the following files:

• mod.rs: Contains the tag struct definition and module exports.
• read.rs: Contains the logic for reading the tag from a file.
• write.rs: Contains the logic for writing the tag to supported formats.

src/
└── foo/
    └── tag/
        ├── mod.rs
        ├── read.rs
        └── write.rs

When adding a new tag, follow these testing requirements:

1. Assets

Place binary test assets in tests/tags/assets/. Name them test.{ext} where {ext} is the tag name (e.g., test.foo). Assets should contain a representative set of tags (Title, Artist, Album, etc.).

2. Unit Tests

Implement at least four unit tests in your tag's read module:

• parse_{tag}: Verifies reading the asset matches a manually constructed tag.
• {tag}_re_read: Verifies a round-trip (Read $\rightarrow$ Write $\rightarrow$ Read) using TagExt::dump_to().
• {tag}_to_tag: Verifies conversion to a generic Tag using verify_tag().
• tag_to_{tag}: Verifies conversion from a generic Tag back to the concrete type using create_tag().

3. Integration Tests

If necessary, place integration tests in tests/tags/.

Feature requests should be categorized into one of two types based on their scope:

Miscellaneous Feature Requests

Use the [MISC] Feature Request template for features that:

• Have no public API.
• Are not fully fleshed out.
• Do not have critical implementation details.

API Feature Requests

Use the [API] Feature Request template if you have a specific design in mind for how the feature should be used. This template is for proposing an API design, not an implementation. Provide a code sketch of the intended interface.

pub struct MyTag {
    some_field: ty,
    some_other_field: ty,
    // ... omit other fields if extending an existing type
}

impl MyTag {
    pub fn foo(&self) -> String;
}

The Accessor trait provides the primary interface for interacting with tag items (like title, artist, or album). You must implement the getters, setters, and removers for the specific items your tag supports.

Implementation Note: If your tag format allows keys to appear multiple times, implement both insert (which replaces existing occurrences) and push (which appends to the list).

impl Accessor for FooTag {
    fn title(&self) -> Option<Cow<'_, str>> { /* implementation */ }
    fn set_title(&mut self, value: String) { /* implementation */ }
    fn remove_title(&mut self) { /* implementation */ }

    // ... repeat for artist, album, etc.
}