Struct lofty::id3::v2::Id3v2Tag

pub struct Id3v2Tag { /* private fields */ }

An ID3v2 tag

Supported file types

• FileType::Aac
• FileType::Aiff
• FileType::Mpeg
• FileType::Wav
• FileType::Ape (READ ONLY)
• FileType::Flac (READ ONLY)
• FileType::Mpc (READ ONLY)

Conversions

⚠ Warnings ⚠

From Tag

When converting from a Tag to an Id3v2Tag, some frames may need editing.

• ItemKey::Comment and ItemKey::Lyrics - Unlike a normal text frame, these require a language. See CommentFrame and UnsynchronizedTextFrame respectively. 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 ItemKey by their description. Some variants exist for these descriptions, such as the one for ReplayGain, otherwise ItemKey::Unknown will be used.
• Frame 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::Binary value under the ItemKey::Popularimeter key.

Special Frames

ID3v2 has GEOB and SYLT frames, which are not parsed by default, instead storing them as FrameValue::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

impl Id3v2Tag

pub fn new() -> Self

Create a new empty ID3v2Tag

Examples

use lofty::id3::v2::Id3v2Tag;
use lofty::TagExt;

let id3v2_tag = Id3v2Tag::new();
assert!(id3v2_tag.is_empty());

pub fn flags(&self) -> &Id3v2TagFlags

Returns the Id3v2TagFlags

pub fn set_flags(&mut self, flags: Id3v2TagFlags)

Restrict the tag’s flags

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.

impl Id3v2Tag

pub fn get(&self, id: &FrameId<'_>) -> Option<&Frame<'static>>

Gets a Frame from an id

pub fn get_text(&self, id: &FrameId<'_>) -> Option<Cow<'_, str>>

Gets the text for a frame

NOTE: This will not work for TXXX frames, use Id3v2Tag::get_user_text for that.

If the tag is Id3v2Version::V4, this will allocate if the text contains any null ('\0') text separators to replace them with a slash ('/').

pub fn get_texts(&self, id: &FrameId<'_>) -> Option<impl Iterator<Item = &str>>

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::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"));

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"));

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::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"));

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)

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::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());

pub fn remove( &mut self, id: &FrameId<'_> ) -> impl Iterator<Item = Frame<'static>> + '_

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::id3::v2::{Frame, FrameFlags, FrameId, Id3v2Tag, TextInformationFrame};
use lofty::{TagExt, TextEncoding};
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::new(
	MOOD_FRAME_ID,
	TextInformationFrame {
		encoding: TextEncoding::Latin1,
		value: String::from("Classical"),
	},
	FrameFlags::default(),
)?;

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());

pub fn retain<P>(&mut self, predicate: P)where P: FnMut(&Frame<'_>) -> bool,

Retains Frames by evaluating the predicate

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.

pub fn remove_picture_type(&mut self, picture_type: PictureType)

Removes a certain PictureType

pub fn unsync_text( &self ) -> impl Iterator<Item = &UnsynchronizedTextFrame> + Clone

Returns all USLT frames

pub fn comments(&self) -> impl Iterator<Item = &CommentFrame>

Returns all COMM frames with an empty content descriptor

Trait Implementations

impl Accessor for Id3v2Tag

fn title(&self) -> Option<Cow<'_, str>>

Returns the title

fn set_title(&mut self, value: String)

Sets the title

fn remove_title(&mut self)

Removes the title

fn artist(&self) -> Option<Cow<'_, str>>

Returns the artist

fn set_artist(&mut self, value: String)

Sets the artist

fn remove_artist(&mut self)

Removes the artist

fn album(&self) -> Option<Cow<'_, str>>

Returns the album

fn set_album(&mut self, value: String)

Sets the album

fn remove_album(&mut self)

Removes the album

fn genre(&self) -> Option<Cow<'_, str>>

Returns the genre

fn set_genre(&mut self, value: String)

Sets the genre

fn remove_genre(&mut self)

Removes the genre

fn track(&self) -> Option<u32>

Returns the track

fn set_track(&mut self, value: u32)

Sets the track

fn remove_track(&mut self)

Removes the track

fn track_total(&self) -> Option<u32>

Returns the track total

fn set_track_total(&mut self, value: u32)

Sets the track total

fn remove_track_total(&mut self)

Removes the track total

fn disk(&self) -> Option<u32>

Returns the disk

fn set_disk(&mut self, value: u32)

Sets the disk

fn remove_disk(&mut self)

Removes the disk

fn disk_total(&self) -> Option<u32>

Returns the disk total

fn set_disk_total(&mut self, value: u32)

Sets the disk total

fn remove_disk_total(&mut self)

Removes the disk total

fn year(&self) -> Option<u32>

Returns the year

fn set_year(&mut self, value: u32)

Sets the year

fn remove_year(&mut self)

Removes the year

fn comment(&self) -> Option<Cow<'_, str>>

Returns the comment

fn set_comment(&mut self, value: String)

Sets the comment

fn remove_comment(&mut self)

Removes the comment

impl Clone for Id3v2Tag

fn clone(&self) -> Id3v2Tag

Returns a copy of the value.

fn clone_from(&mut self, source: &Self)

Performs copy-assignment from source.

impl Debug for Id3v2Tag

fn fmt(&self, f: &mut Formatter<'_>) -> Result

Formats the value using the given formatter.

impl Default for Id3v2Tag

fn default() -> Self

Returns the “default value” for a type.

impl From<Id3v2Tag> for Tag

fn from(input: Id3v2Tag) -> Self

Converts to this type from the input type.

impl From<Tag> for Id3v2Tag

fn from(input: Tag) -> Self

Converts to this type from the input type.

impl<'a> IntoIterator for &'a Id3v2Tag

type Item = &'a Frame<'static>

The type of the elements being iterated over.

type IntoIter = Iter<'a, Frame<'static>>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl IntoIterator for Id3v2Tag

type Item = Frame<'static>

The type of the elements being iterated over.

type IntoIter = IntoIter<<Id3v2Tag as IntoIterator>::Item>

Which kind of iterator are we turning this into?

fn into_iter(self) -> Self::IntoIter

Creates an iterator from a value.

impl PartialEq for Id3v2Tag

fn eq(&self, other: &Id3v2Tag) -> bool

This method tests for self and other values to be equal, and is used by ==.

fn ne(&self, other: &Rhs) -> bool

This method tests for !=. The default implementation is almost always sufficient, and should not be overridden without very good reason.

impl SplitTag for Id3v2Tag

type Remainder = SplitTagRemainder

The remainder of the split operation that is not represented in the resulting Tag.

fn split_tag(self) -> (Self::Remainder, Tag)

Extract and split generic contents into a Tag.

impl TagExt for Id3v2Tag

fn save_to(&self, file: &mut File) -> Result<(), Self::Err>

Writes the tag to a file

Errors

• Attempting to write the tag to a format that does not support it
• Attempting to write an encrypted frame without a valid method symbol or data length indicator
• Attempting to write an invalid FrameId/FrameValue pairing

fn dump_to<W: Write>(&self, writer: &mut W) -> Result<(), Self::Err>

Dumps the tag to a writer

Errors

• std::io::Error
• ErrorKind::TooMuchData

type Err = LoftyError

The associated error which can be returned from IO operations

type RefKey<'a> = &'a FrameId<'a>

The type of key used in the tag for non-mutating functions

fn len(&self) -> usize

Returns the number of items in the tag

fn contains<'a>(&'a self, key: Self::RefKey<'a>) -> bool

Whether the tag contains an item with the key

fn is_empty(&self) -> bool

Whether the tag has any items

fn remove_from_path<P: AsRef<Path>>(&self, path: P) -> Result<(), Self::Err>

Remove a tag from a Path

fn remove_from(&self, file: &mut File) -> Result<(), Self::Err>

Remove a tag from a File

fn clear(&mut self)

Clear the tag, removing all items

fn save_to_path<P: AsRef<Path>>(&self, path: P) -> Result<(), Self::Err>

Save the tag to a path

impl Eq for Id3v2Tag

impl StructuralEq for Id3v2Tag

impl StructuralPartialEq for Id3v2Tag