pub struct Id3v2Tag { /* private fields */ }Expand description
An ID3v2 tag
§Supported file types
FileType::AacFileType::AiffFileType::MpegFileType::WavFileType::Ape(READ ONLY)FileType::Flac(READ ONLY)FileType::Mpc(READ ONLY)
§Accessor Methods
As ID3v2.4 allows for multiple values to exist in a single frame, the raw strings, as provided by Id3v2Tag::get_text
may contain null separators.
In the Accessor methods, these values have the separators (\0) replaced with "/" for convenience.
§Conversions
⚠ Warnings ⚠
§From Tag
When converting from a Tag to an Id3v2Tag, some frames may need editing.
ItemKey::CommentandItemKey::Lyrics- Unlike a normal text frame, these require a language. SeeCommentFrameandUnsynchronizedTextFramerespectively. An attempt is made to create this information, but it may be incorrect.language- Unknown and set to “XXX”description- Left empty, which is invalid if there are more than one of these frames. These frames can only be identified by their descriptions, and as such they are expected to be unique for each.
ItemKey::Unknown("WXXX" | "TXXX")- These frames are also identified by their descriptions.
§To Tag
- TXXX/WXXX - These frames will be stored as an
ItemKeyby their description. Some variants exist for these descriptions, such as the one forReplayGain, otherwiseItemKey::Unknownwill be used. - Frames that require a language (COMM/USLT) - With ID3v2 being the only format that allows for language-specific items, this information is not retained.
- POPM - These frames will be stored as a raw
ItemValue::Binaryvalue under theItemKey::Popularimeterkey.
§Special Frames
ID3v2 has GEOB and SYLT frames, which are not parsed by default, instead storing them as [FrameType::Binary].
They can easily be parsed with GeneralEncapsulatedObject::parse
and SynchronizedText::parse respectively, and converted back to binary with
GeneralEncapsulatedObject::as_bytes and
SynchronizedText::as_bytes for writing.
Implementations§
Source§impl Id3v2Tag
impl Id3v2Tag
Sourcepub fn new() -> Self
pub fn new() -> Self
Create a new empty ID3v2Tag
§Examples
use lofty::id3::v2::Id3v2Tag;
use lofty::tag::TagExt;
let id3v2_tag = Id3v2Tag::new();
assert!(id3v2_tag.is_empty());Sourcepub fn flags(&self) -> &Id3v2TagFlags
pub fn flags(&self) -> &Id3v2TagFlags
Returns the Id3v2TagFlags
Sourcepub fn set_flags(&mut self, flags: Id3v2TagFlags)
pub fn set_flags(&mut self, flags: Id3v2TagFlags)
Restrict the tag’s flags
Sourcepub fn original_version(&self) -> Id3v2Version
pub fn original_version(&self) -> Id3v2Version
The original version of the tag
This is here, since the tag is upgraded to ID3v2.4, but a v2.2 or v2.3
tag may have been read.
Source§impl Id3v2Tag
impl Id3v2Tag
Sourcepub fn get_text(&self, id: &FrameId<'_>) -> Option<&str>
pub fn get_text(&self, id: &FrameId<'_>) -> Option<&str>
Gets the text for a frame
NOTE: If the tag is Id3v2Version::V4, there could be multiple values separated by null characters ('\0').
Use Id3v2Tag::get_texts to conveniently split all of the values.
NOTE: This will not work for TXXX frames, use Id3v2Tag::get_user_text for that.
§Examples
use lofty::id3::v2::{FrameId, Id3v2Tag};
use lofty::tag::Accessor;
use std::borrow::Cow;
const TITLE_ID: FrameId<'_> = FrameId::Valid(Cow::Borrowed("TIT2"));
let mut tag = Id3v2Tag::new();
tag.set_title(String::from("Foo"));
let title = tag.get_text(&TITLE_ID);
assert_eq!(title, Some("Foo"));
// Now we have a string with multiple values
tag.set_title(String::from("Foo\0Bar"));
// Null separator is retained! This case is better handled by `get_texts`.
let title = tag.get_text(&TITLE_ID);
assert_eq!(title, Some("Foo\0Bar"));Sourcepub fn get_texts<'a>(
&'a self,
id: &FrameId<'_>,
) -> Option<impl Iterator<Item = &'a str> + use<'a>>
pub fn get_texts<'a>( &'a self, id: &FrameId<'_>, ) -> Option<impl Iterator<Item = &'a str> + use<'a>>
Gets all of the values for a text frame
NOTE: Multiple values are only supported in ID3v2.4, this will not be very useful for ID3v2.2/3 tags.
§Examples
use lofty::id3::v2::{FrameId, Id3v2Tag};
use lofty::tag::Accessor;
use std::borrow::Cow;
const TITLE_ID: FrameId<'_> = FrameId::Valid(Cow::Borrowed("TIT2"));
let mut tag = Id3v2Tag::new();
tag.set_title(String::from("Foo\0Bar"));
let mut titles = tag.get_texts(&TITLE_ID).expect("Should exist");
assert_eq!(titles.next(), Some("Foo"));
assert_eq!(titles.next(), Some("Bar"));Sourcepub fn get_user_text(&self, description: &str) -> Option<&str>
pub fn get_user_text(&self, description: &str) -> Option<&str>
Gets the text for a user-defined frame
NOTE: If the tag is Id3v2Version::V4, there could be multiple values separated by null characters ('\0').
The caller is responsible for splitting these values as necessary.
§Examples
use lofty::id3::v2::Id3v2Tag;
let mut tag = Id3v2Tag::new();
// Add a new "TXXX" frame identified by "SOME_DESCRIPTION"
let _ = tag.insert_user_text(String::from("SOME_DESCRIPTION"), String::from("Some value"));
// Now we can get the value back using the description
let value = tag.get_user_text("SOME_DESCRIPTION");
assert_eq!(value, Some("Some value"));Sourcepub fn insert_user_text(
&mut self,
description: String,
content: String,
) -> Option<Frame<'static>>
pub fn insert_user_text( &mut self, description: String, content: String, ) -> Option<Frame<'static>>
Inserts a new user-defined text frame (TXXX)
NOTE: The encoding will be UTF-8
This will replace any TXXX frame with the same description, see Id3v2Tag::insert.
§Examples
use lofty::id3::v2::Id3v2Tag;
use lofty::tag::TagExt;
let mut tag = Id3v2Tag::new();
assert!(tag.is_empty());
// Add a new "TXXX" frame identified by "SOME_DESCRIPTION"
let _ = tag.insert_user_text(String::from("SOME_DESCRIPTION"), String::from("Some value"));
// Now we can get the value back using `get_user_text`
let value = tag.get_user_text("SOME_DESCRIPTION");
assert_eq!(value, Some("Some value"));Sourcepub fn insert(&mut self, frame: Frame<'static>) -> Option<Frame<'static>>
pub fn insert(&mut self, frame: Frame<'static>) -> Option<Frame<'static>>
Inserts a Frame
This will replace any frame of the same id (or description! See ExtendedTextFrame)
Sourcepub fn remove_user_text(&mut self, description: &str) -> Option<Frame<'static>>
pub fn remove_user_text(&mut self, description: &str) -> Option<Frame<'static>>
Removes a user-defined text frame (TXXX) by its description
This will return the matching frame.
§Examples
use lofty::id3::v2::Id3v2Tag;
use lofty::tag::TagExt;
let mut tag = Id3v2Tag::new();
assert!(tag.is_empty());
// Add a new "TXXX" frame identified by "SOME_DESCRIPTION"
let _ = tag.insert_user_text(String::from("SOME_DESCRIPTION"), String::from("Some value"));
assert!(!tag.is_empty());
// Now we can remove it by its description
let value = tag.remove_user_text("SOME_DESCRIPTION");
assert!(tag.is_empty());Sourcepub fn remove<'a>(
&'a mut self,
id: &FrameId<'_>,
) -> impl Iterator<Item = Frame<'static>> + use<'a>
pub fn remove<'a>( &'a mut self, id: &FrameId<'_>, ) -> impl Iterator<Item = Frame<'static>> + use<'a>
Removes a Frame by id
This will remove any frames with the same ID. To remove TXXX frames by their descriptions,
see Id3v2Tag::remove_user_text.
§Examples
use lofty::TextEncoding;
use lofty::id3::v2::{Frame, FrameFlags, FrameId, Id3v2Tag, TextInformationFrame};
use lofty::tag::TagExt;
use std::borrow::Cow;
const MOOD_FRAME_ID: FrameId<'static> = FrameId::Valid(Cow::Borrowed("TMOO"));
let mut tag = Id3v2Tag::new();
assert!(tag.is_empty());
// Add a new "TMOO" frame
let tmoo_frame = Frame::Text(TextInformationFrame::new(
MOOD_FRAME_ID,
TextEncoding::Latin1,
String::from("Classical"),
));
let _ = tag.insert(tmoo_frame.clone());
assert!(!tag.is_empty());
// Now we can remove it by its ID
let mut values = tag.remove(&MOOD_FRAME_ID);
// We got back exactly what we inserted
assert_eq!(values.next(), Some(tmoo_frame));
assert!(values.next().is_none());
drop(values);
// The tag is now empty
assert!(tag.is_empty());Sourcepub fn insert_picture(&mut self, picture: Picture) -> Option<Frame<'static>>
pub fn insert_picture(&mut self, picture: Picture) -> Option<Frame<'static>>
Inserts a Picture
According to spec, there can only be one picture of type PictureType::Icon and PictureType::OtherIcon.
When attempting to insert these types, if another is found it will be removed and returned.
Sourcepub fn remove_picture_type(&mut self, picture_type: PictureType)
pub fn remove_picture_type(&mut self, picture_type: PictureType)
Removes a certain PictureType
Sourcepub fn unsync_text(
&self,
) -> impl Iterator<Item = &UnsynchronizedTextFrame<'_>> + Clone
pub fn unsync_text( &self, ) -> impl Iterator<Item = &UnsynchronizedTextFrame<'_>> + Clone
Returns all USLT frames
Sourcepub fn comments(&self) -> impl Iterator<Item = &CommentFrame<'_>>
pub fn comments(&self) -> impl Iterator<Item = &CommentFrame<'_>>
Returns all COMM frames with an empty content descriptor