Merge branch 'main' into Add-CountryRelease

Author: UnknownSuperficialNight

.github/workflows/bench.yml

@@ -29,14 +29,14 @@ jobs:
                 run: |
                     sudo apt-get update
                     sudo apt-get install -y valgrind
-            -   name: Install iai-callgrind-runner
+            -   name: Install gungraun-runner
                 run: |
                     version=$(cargo metadata --format-version=1 |\
-                      jq '.packages[] | select(.name == "iai-callgrind").version' |\
+                      jq '.packages[] | select(.name == "gungraun").version' |\
                       tr -d '"'
                     )
-                    cargo install iai-callgrind-runner --version $version
+                    cargo install gungraun-runner --version $version
             -   uses: bencherdev/bencher@main
             -   name: Run Bencher
                 run: |
-                    bencher run --adapter rust_iai_callgrind --err "cargo bench"
+                    bencher run --adapter rust_gungraun --err "cargo bench"

CHANGELOG.md

@@ -7,13 +7,21 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 ## [Unreleased]
 
 ### Added
-- **ItemKey**: `ItemKey::AlbumArtists`, available for ID3v2, Vorbis Comments, APE, and MP4 Ilst ([PR](https://github.com/Serial-ATA/lofty-rs/pull/523))
-    - This is a multi-value item that stores each artist for a track. It should be retrieved with `Tag::get_strings` or `Tag::take_strings`.
-    - For example, a track has `ItemKey::TrackArtist` = "Foo & Bar", then `ItemKey::AlbumArtists` = ["Foo", "Bar"].
+- **ItemKey**:
+  - `ItemKey::AlbumArtists`, available for ID3v2, Vorbis Comments, APE, and MP4 Ilst ([PR](https://github.com/Serial-ATA/lofty-rs/pull/523))
+      - This is a multi-value item that stores each artist for a track. It should be retrieved with `Tag::get_strings` or `Tag::take_strings`.
+      - For example, a track has `ItemKey::TrackArtist` = "Foo & Bar", then `ItemKey::AlbumArtists` = ["Foo", "Bar"].
+  - `ItemKey::UnsyncLyrics` ([issue](https://github.com/Serial-ATA/lofty-rs/issues/561)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/568))
+    - In formats like Vorbis Comments, `ItemKey::Lyrics` may actually contain synchronized lyrics in LRC format. To help with the ambiguity, some
+      apps may write a separate field containing normal, unsynchronized lyrics.
+    - In other formats where the difference doesn't matter (like ID3v2), this will act exactly the same as `ItemKey::Lyrics`.
 - **Serde**: [Serde] support for `*Type` enums (`FileType`, `TagType`, `PictureType`)
   - Support can be enabled with the new `serde` feature (not enabled by default)
 - **Probe**: `Probe::read_bound()` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/557))
   - Same as `Probe::read()`, but returns a [`BoundTaggedFile`](https://docs.rs/lofty/latest/lofty/file/struct.BoundTaggedFile.html)
+- **Other**: `EXTENSIONS` list containing common file extensions for all supported audio file types ([issue](https://github.com/Serial-ATA/lofty-rs/issues/509)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/558))
+  - This is useful for filtering files when scanning directories. If your app uses extension filtering, **please consider switching to this**, as to not
+    miss any supported files.
 
 ### Changed
 - **ID3v2**: Check `TXXX:ALBUMARTIST` and `TXXX:ALBUM ARTIST` for `ItemKey::AlbumArtist` conversions
@@ -22,6 +30,10 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
     - These fields will now properly be split into `DISCNUMBER` and `DISCTOTAL`, making it possible to use them with
       [Accessor::disk()](https://docs.rs/lofty/latest/lofty/tag/trait.Accessor.html#method.disk) and [Accessor::disk_total()](https://docs.rs/lofty/latest/lofty/tag/trait.Accessor.html#method.disk_total).
 * **ItemKey**: `ItemKey` is now `Copy` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/526))
+* **FileType**: Replaced `FileType::supports_tag_type()` with `FileType::tag_support()` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/566))
+  * Rather than a simple `bool`, this now returns a `TagSupport`, which can describe three states: unsupported, read-only, and read/write
+* **TaggedFileExt**: Replaced `TaggedFileExt::supports_tag_type()` with `TaggedFileExt::tag_support()` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/566))
+* **FileResolver**: Replaced `FileResolver::supported_tag_types()` with `FileResolver::tag_support()` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/566))
 
 ### Fixed
 - **ID3v2**: Support parsing UTF-16 `COMM`/`USLT` frames with a single BOM ([issue](https://github.com/Serial-ATA/lofty-rs/issues/532)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/535))
@@ -35,6 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 * **ItemKey**: `ItemKey::Unknown` ([PR](https://github.com/Serial-ATA/lofty-rs/pull/526))
     * `Tag` is now intended for generic metadata editing only, with format-specific items only being available through concrete tag types.
       See <https://github.com/Serial-ATA/lofty-rs/issues/521> for the rationale.
+* **Picture**: `Picture::new_unchecked()`, replaced with `Picture::unchecked()` returning a builder ([issue](https://github.com/Serial-ATA/lofty-rs/issues/468)) ([PR](https://github.com/Serial-ATA/lofty-rs/pull/569))
 
 ## [0.22.4] - 2025-04-29
 

benches/create_tag.rs

@@ -13,7 +13,7 @@ use lofty::tag::{Accessor, TagExt};
 
 use std::borrow::Cow;
 
-use iai_callgrind::{library_benchmark, library_benchmark_group, main};
+use gungraun::{library_benchmark, library_benchmark_group, main};
 
 const ENCODER: &str = "Lavf57.56.101";
 
@@ -44,12 +44,10 @@ bench_tag_write!([
 		use lofty::ape::ApeItem;
 		use lofty::tag::ItemValue;
 
-		let picture = Picture::new_unchecked(
-			PictureType::CoverFront,
-			Some(MimeType::Jpeg),
-			None,
-			include_bytes!("./assets/cover.jpg").to_vec(),
-		);
+		let picture = Picture::unchecked(include_bytes!("./assets/cover.jpg").to_vec())
+			.pic_type(PictureType::CoverFront)
+			.mime_type(MimeType::Jpeg)
+			.build();
 
 		tag.insert(
 			ApeItem::new(
@@ -70,12 +68,10 @@ bench_tag_write!([
 		use lofty::TextEncoding;
 		use lofty::id3::v2::{Frame, TextInformationFrame};
 
-		let picture = Picture::new_unchecked(
-			PictureType::CoverFront,
-			Some(MimeType::Jpeg),
-			None,
-			include_bytes!("./assets/cover.jpg").to_vec(),
-		);
+		let picture = Picture::unchecked(include_bytes!("./assets/cover.jpg").to_vec())
+			.pic_type(PictureType::CoverFront)
+			.mime_type(MimeType::Jpeg)
+			.build();
 
 		tag.insert_picture(picture);
 		tag.insert(Frame::Text(TextInformationFrame::new(
@@ -88,12 +84,10 @@ bench_tag_write!([
 	(ilst, Ilst, |tag| {
 		use lofty::mp4::{Atom, AtomData, AtomIdent};
 
-		let picture = Picture::new_unchecked(
-			PictureType::CoverFront,
-			Some(MimeType::Jpeg),
-			None,
-			include_bytes!("./assets/cover.jpg").to_vec(),
-		);
+		let picture = Picture::unchecked(include_bytes!("./assets/cover.jpg").to_vec())
+			.pic_type(PictureType::CoverFront)
+			.mime_type(MimeType::Jpeg)
+			.build();
 
 		tag.insert_picture(picture);
 		tag.insert(Atom::new(
@@ -107,12 +101,10 @@ bench_tag_write!([
 	(vorbis_comments, VorbisComments, |tag| {
 		use lofty::ogg::OggPictureStorage;
 
-		let picture = Picture::new_unchecked(
-			PictureType::CoverFront,
-			Some(MimeType::Jpeg),
-			None,
-			include_bytes!("./assets/cover.jpg").to_vec(),
-		);
+		let picture = Picture::unchecked(include_bytes!("./assets/cover.jpg").to_vec())
+			.pic_type(PictureType::CoverFront)
+			.mime_type(MimeType::Jpeg)
+			.build();
 
 		let _ = tag.insert_picture(picture, None).unwrap();
 		tag.push(String::from("ENCODER"), String::from(ENCODER));

benches/read_file.rs

@@ -3,7 +3,7 @@
 use lofty::config::ParseOptions;
 use lofty::probe::Probe;
 
-use iai_callgrind::{library_benchmark, library_benchmark_group, main};
+use gungraun::{library_benchmark, library_benchmark_group, main};
 
 use std::hint::black_box;
 use std::io::Cursor;

doc/NEW_FILE.md

@@ -198,11 +198,11 @@ Then we'll store our tests in `tests/files/{format}.rs`.
 There is a simple suite of tests to go in that file:
 
 * `read()`: Read a file containing all possible tags (a Foo file with an ID3v2 *and* APE tag in this case), verifying
-  all expected information is present. This can be done quickly with the `crate::verify_artist!` macro.
-* `write()`: Change the artist field of each tag using the `crate::set_artist!` macro, which will verify the artist
+  all expected information is present. This can be done quickly with the `crate::verify_artist()` function.
+* `write()`: Change the artist field of each tag using the `crate::set_artist()` function, which will verify the artist
   and set a new one. Then, revert the artists using the same method.
 * `remove_{tag}()`: For each tag format the file supports, create a `remove_{tag}()` test that simply calls the
-  `crate::remove_tag!` macro. For example, this format would have `remove_ape()` and `remove_id3v2()`.
+  `crate::remove_tag_test()` function. For example, this format would have `remove_ape()` and `remove_id3v2()`.
 
 #### Fuzz Tests
 

examples/custom_resolver/src/main.rs

@@ -7,7 +7,7 @@ use lofty::file::FileType;
 use lofty::id3::v2::Id3v2Tag;
 use lofty::properties::FileProperties;
 use lofty::resolve::FileResolver;
-use lofty::tag::TagType;
+use lofty::tag::{TagSupport, TagType};
 use lofty_attr::LoftyFile;
 
 use std::fs::File;
@@ -73,8 +73,11 @@ impl FileResolver for MyFile {
 
 	// All of the `TagType`s this file supports, including the
 	// primary one.
-	fn supported_tag_types() -> &'static [TagType] {
-		&[TagType::Id3v2, TagType::Ape]
+	fn tag_support(tag_type: TagType) -> TagSupport {
+		match tag_type {
+			TagType::Id3v2 | TagType::Ape => TagSupport::ReadWrite,
+			_ => TagSupport::Unsupported,
+		}
 	}
 
 	// This is used to guess the `FileType` when reading the file contents.

lofty/Cargo.toml

@@ -47,7 +47,7 @@ rusty-fork = "0.3.0"
 structopt = { version = "0.3.26", default-features = false }
 tempfile  = "3.15.0"
 test-log = "0.2.16"
-iai-callgrind = "0.16.0"
+gungraun = "0.17.0"
 
 [lints]
 workspace = true

lofty/src/ape/tag/mod.rs

@@ -920,12 +920,10 @@ mod tests {
 
 	#[test_log::test]
 	fn skip_reading_cover_art() {
-		let p = Picture::new_unchecked(
-			PictureType::CoverFront,
-			Some(MimeType::Jpeg),
-			None,
-			std::iter::repeat(0).take(50).collect::<Vec<u8>>(),
-		);
+		let p = Picture::unchecked(std::iter::repeat(0).take(50).collect::<Vec<u8>>())
+			.pic_type(PictureType::CoverFront)
+			.mime_type(MimeType::Jpeg)
+			.build();
 
 		let mut tag = Tag::new(TagType::Ape);
 		tag.push_picture(p);

lofty/src/file/file_type.rs

@@ -1,10 +1,48 @@
 use crate::config::global_options;
 use crate::resolve::custom_resolvers;
-use crate::tag::TagType;
+use crate::tag::{TagSupport, TagType};
 
 use std::ffi::OsStr;
 use std::path::Path;
 
+/// List of common audio extensions
+///
+/// This contains a bunch of common extensions for all supported [`FileType`]s, and can be used a filter
+/// when scanning directories.
+///
+/// NOTE: This is **not** an exhaustive list, but it should work fine in most cases.
+///
+/// # Examples
+///
+/// ```rust,no_run
+/// use lofty::file::EXTENSIONS;
+/// use std::fs;
+///
+/// # fn main() -> lofty::error::Result<()> {
+/// for entry in fs::read_dir(".")? {
+/// 	let entry = entry?;
+///
+/// 	let path = entry.path();
+/// 	let Some(extension) = path.extension() else {
+/// 		continue;
+/// 	};
+///
+/// 	// Skip any non-audio file extensions
+/// 	if !EXTENSIONS.iter().any(|e| *e == extension) {
+/// 		continue;
+/// 	}
+///
+/// 	// `entry` is *most likely* a supported file at this point
+/// 	let parsed = lofty::read_from_path(path)?;
+/// }
+/// # Ok(()) }
+/// ```
+pub const EXTENSIONS: &[&str] = &[
+	// Also update `FileType::from_ext()` below
+	"aac", "ape", "aiff", "aif", "afc", "aifc", "mp3", "mp2", "mp1", "wav", "wv", "opus", "flac",
+	"ogg", "mp4", "m4a", "m4b", "m4p", "m4r", "m4v", "3gp", "mpc", "mp+", "mpp", "spx",
+];
+
 /// The type of file read
 #[cfg_attr(feature = "serde", derive(serde::Serialize, serde::Deserialize))]
 #[derive(PartialEq, Eq, Copy, Clone, Debug)]
@@ -65,11 +103,7 @@ impl FileType {
 		}
 	}
 
-	/// Returns if the target `FileType` supports a [`TagType`]
-	///
-	/// NOTE: This is feature dependent, meaning if you do not have the
-	///       `id3v2` feature enabled, [`FileType::Mpeg`] will return `false` for
-	///        [`TagType::Id3v2`].
+	/// Describes how this `FileType` supports the given [`TagType`]
 	///
 	/// # Panics
 	///
@@ -81,24 +115,48 @@ impl FileType {
 	/// use lofty::file::FileType;
 	/// use lofty::tag::TagType;
 	///
-	/// let file_type = FileType::Mpeg;
-	/// assert!(file_type.supports_tag_type(TagType::Id3v2));
+	/// // `FileType::Mpeg` supports both reading and writing ID3v2
+	/// assert!(FileType::Mpeg.tag_support(TagType::Id3v2).is_writable());
 	/// ```
-	pub fn supports_tag_type(&self, tag_type: TagType) -> bool {
+	pub fn tag_support(&self, tag_type: TagType) -> TagSupport {
 		if let FileType::Custom(c) = self {
 			let resolver = crate::resolve::lookup_resolver(c);
-			return resolver.supported_tag_types().contains(&tag_type);
+			return resolver.tag_support(tag_type);
 		}
 
-		match tag_type {
-			TagType::Ape => crate::ape::ApeTag::SUPPORTED_FORMATS.contains(self),
-			TagType::Id3v1 => crate::id3::v1::Id3v1Tag::SUPPORTED_FORMATS.contains(self),
-			TagType::Id3v2 => crate::id3::v2::Id3v2Tag::SUPPORTED_FORMATS.contains(self),
-			TagType::Mp4Ilst => crate::mp4::Ilst::SUPPORTED_FORMATS.contains(self),
-			TagType::VorbisComments => crate::ogg::VorbisComments::SUPPORTED_FORMATS.contains(self),
-			TagType::RiffInfo => crate::iff::wav::RiffInfoList::SUPPORTED_FORMATS.contains(self),
-			TagType::AiffText => crate::iff::aiff::AiffTextChunks::SUPPORTED_FORMATS.contains(self),
+		macro_rules! tag_support {
+			(
+				$tag_type:ident,
+				$(($variant:ident, $tag:path)),* $(,)?
+			) => {
+				match $tag_type {
+					$(
+						TagType::$variant => {
+							if <$tag>::SUPPORTED_FORMATS.contains(self) {
+								if <$tag>::READ_ONLY_FORMATS.contains(self) {
+									return TagSupport::ReadOnly;
+								}
+
+								return TagSupport::ReadWrite;
+							}
+
+							TagSupport::Unsupported
+						},
+					)*
+				}
+			}
 		}
+
+		tag_support!(
+			tag_type,
+			(Ape, crate::ape::ApeTag),
+			(Id3v1, crate::id3::v1::Id3v1Tag),
+			(Id3v2, crate::id3::v2::Id3v2Tag),
+			(Mp4Ilst, crate::mp4::Ilst),
+			(VorbisComments, crate::ogg::VorbisComments),
+			(RiffInfo, crate::iff::wav::RiffInfoList),
+			(AiffText, crate::iff::aiff::AiffTextChunks),
+		)
 	}
 
 	/// Attempts to extract a [`FileType`] from an extension
@@ -129,6 +187,7 @@ impl FileType {
 			}
 		}
 
+		// Also update `EXTENSIONS` above
 		match ext.as_str() {
 			"aac" => Some(Self::Aac),
 			"ape" => Some(Self::Ape),

lofty/src/file/mod.rs

@@ -5,7 +5,7 @@ mod file_type;
 mod tagged_file;
 
 pub use audio_file::AudioFile;
-pub use file_type::FileType;
+pub use file_type::{EXTENSIONS, FileType};
 pub use tagged_file::{BoundTaggedFile, TaggedFile, TaggedFileExt};
 
 pub(crate) use file_type::FileTypeGuessResult;