Struct Tag

pub struct Tag { /* private fields */ }

An ID3 tag containing zero or more Frames.

Implementations

impl<'a> Tag

pub fn new() -> Tag

Creates a new ID3v2.4 tag with no frames.

pub fn with_version(version: Version) -> Tag

Used for creating new tag with a specific version.

pub fn is_candidate(reader: impl Read + Seek) -> Result<bool>

Will return true if the reader is a candidate for an ID3 tag. The reader position will be reset back to the previous position before returning.

pub fn skip(reader: impl Read + Seek) -> Result<bool>

Detects the presence of an ID3v2 tag at the current position of the reader and skips it if is found. Returns true if a tag was found.

pub fn remove_from_path(path: impl AsRef<Path>) -> Result<bool>

Removes an ID3v2 tag from the file at the specified path.

Returns true if the file initially contained a tag.

pub fn remove_from_file(file: impl StorageFile) -> Result<bool>

Removes an ID3v2 tag from the specified file.

Returns true if the file initially contained a tag.

pub fn read_from(reader: impl Read) -> Result<Tag>

👎Deprecated: use read_from2

Attempts to read an ID3 tag from the reader.

pub fn read_from2(reader: impl Read + Seek) -> Result<Tag>

Attempts to read an ID3 tag from the reader.

The file format is detected using header magic.

In the case of both Aiff/Wav tags and a ID3 header being present, the header takes precense.

pub fn read_from_path(path: impl AsRef<Path>) -> Result<Tag>

Attempts to read an ID3 tag from the file at the indicated path.

pub fn read_from_aiff(reader: impl Read + Seek) -> Result<Tag>

👎Deprecated: use read_from

Reads an AIFF stream and returns any present ID3 tag.

pub fn read_from_aiff_path(path: impl AsRef<Path>) -> Result<Tag>

👎Deprecated: use read_from_path

Reads an AIFF file at the specified path and returns any present ID3 tag.

pub fn read_from_aiff_file(file: impl StorageFile) -> Result<Tag>

👎Deprecated: use read_from_file

Reads an AIFF file and returns any present ID3 tag.

pub fn read_from_wav(reader: impl Read + Seek) -> Result<Tag>

👎Deprecated: use read_from

Reads an WAV stream and returns any present ID3 tag.

pub fn read_from_wav_path(path: impl AsRef<Path>) -> Result<Tag>

👎Deprecated: use read_from_path

Reads an WAV file at the specified path and returns any present ID3 tag.

pub fn read_from_wav_file(file: impl StorageFile) -> Result<Tag>

👎Deprecated: use read_from_file

Reads an WAV file and returns any present ID3 tag.

pub fn write_to(&self, writer: impl Write, version: Version) -> Result<()>

Attempts to write the ID3 tag to the writer using the specified version.

Note that the plain tag is written, regardless of the original contents. To safely encode a tag to an MP3 file, use Tag::write_to_file.

pub fn write_to_file( &self, file: impl StorageFile, version: Version, ) -> Result<()>

Attempts to write the ID3 tag from the file at the indicated path. If the specified path is the same path which the tag was read from, then the tag will be written to the padding if possible.

pub fn write_to_path( &self, path: impl AsRef<Path>, version: Version, ) -> Result<()>

Conventience function for [write_to_file].

pub fn write_to_aiff_path( &self, path: impl AsRef<Path>, version: Version, ) -> Result<()>

👎Deprecated: use write_to_path

Overwrite WAV file ID3 chunk in a file

pub fn write_to_aiff_file( &self, file: impl StorageFile, version: Version, ) -> Result<()>

👎Deprecated: use write_to_file

Overwrite AIFF file ID3 chunk in a file. The file must be opened read/write.

pub fn write_to_wav_path( &self, path: impl AsRef<Path>, version: Version, ) -> Result<()>

👎Deprecated: use write_to_path

Overwrite WAV file ID3 chunk

pub fn write_to_wav_file( &self, file: impl StorageFile, version: Version, ) -> Result<()>

👎Deprecated: use write_to_file

Overwrite AIFF file ID3 chunk in a file. The file must be opened read/write.

pub fn version(&self) -> Version

Returns version of the read tag.

pub fn frames(&'a self) -> impl Iterator<Item = &'a Frame> + 'a

Returns an iterator over the all frames in the tag.

Example

use id3::{Content, Frame, Tag, TagLike};

let mut tag = Tag::new();

tag.add_frame(Frame::with_content("TPE1", Content::Text("".to_string())));
tag.add_frame(Frame::with_content("APIC", Content::Text("".to_string())));

assert_eq!(tag.frames().count(), 2);

pub fn extended_texts(&'a self) -> impl Iterator<Item = &'a ExtendedText> + 'a

Returns an iterator over the extended texts in the tag.

pub fn extended_links(&'a self) -> impl Iterator<Item = &'a ExtendedLink> + 'a

Returns an iterator over the extended links in the tag.

pub fn encapsulated_objects( &'a self, ) -> impl Iterator<Item = &'a EncapsulatedObject> + 'a

Returns an iterator over the General Encapsulated Object (GEOB) frames in the tag.

pub fn comments(&'a self) -> impl Iterator<Item = &'a Comment> + 'a

Returns an iterator over the comments in the tag.

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::{Content, Comment};

let mut tag = Tag::new();

let frame = Frame::with_content("COMM", Content::Comment(Comment {
    lang: "eng".to_owned(),
    description: "key1".to_owned(),
    text: "value1".to_owned()
}));
tag.add_frame(frame);

let frame = Frame::with_content("COMM", Content::Comment(Comment {
    lang: "eng".to_owned(),
    description: "key2".to_owned(),
    text: "value2".to_owned()
}));
tag.add_frame(frame);

assert_eq!(tag.comments().count(), 2);

pub fn lyrics(&'a self) -> impl Iterator<Item = &'a Lyrics> + 'a

Returns an iterator over the lyrics frames in the tag.

pub fn synchronised_lyrics( &'a self, ) -> impl Iterator<Item = &'a SynchronisedLyrics> + 'a

Returns an iterator over the synchronised lyrics frames in the tag.

pub fn pictures(&'a self) -> impl Iterator<Item = &'a Picture> + 'a

Returns an iterator over the pictures in the tag.

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::{Content, Picture, PictureType};

let mut tag = Tag::new();

let picture = Picture {
    mime_type: String::new(),
    picture_type: PictureType::Other,
    description: String::new(),
    data: Vec::new(),
};
tag.add_frame(Frame::with_content("APIC", Content::Picture(picture.clone())));
tag.add_frame(Frame::with_content("APIC", Content::Picture(picture.clone())));

assert_eq!(tag.pictures().count(), 1);

pub fn unique_file_identifiers( &'a self, ) -> impl Iterator<Item = &'a UniqueFileIdentifier> + 'a

Returns an iterator over the Unique File Identifiers (ufid) in the tag.

Example

use id3::{Frame, Tag, TagLike};
use id3::frame::{Content, UniqueFileIdentifier};

let mut tag = Tag::new();

let unique_file_identifier = UniqueFileIdentifier {
    owner_identifier: String::from("http://www.id3.org/dummy/ufid.html"),
    identifier: "7FZo5fMqyG5Ys1dm8F1FHa".into(),
};
tag.add_frame(Frame::with_content("UFID", Content::UniqueFileIdentifier(unique_file_identifier.clone())));
tag.add_frame(Frame::with_content("UFID", Content::UniqueFileIdentifier(unique_file_identifier.clone())));

assert_eq!(tag.unique_file_identifiers().count(), 1);

pub fn chapters(&self) -> impl Iterator<Item = &Chapter>

Returns an iterator over all chapters (CHAP) in the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{Chapter, Content, Frame};

let mut tag = Tag::new();
tag.add_frame(Chapter{
    element_id: "01".to_string(),
    start_time: 1000,
    end_time: 2000,
    start_offset: 0xff,
    end_offset: 0xff,
    frames: Vec::new(),
});
tag.add_frame(Chapter{
    element_id: "02".to_string(),
    start_time: 2000,
    end_time: 3000,
    start_offset: 0xff,
    end_offset: 0xff,
    frames: Vec::new(),
});
assert_eq!(2, tag.chapters().count());

pub fn tables_of_contents(&self) -> impl Iterator<Item = &TableOfContents>

Returns an iterator over all tables of contents (CTOC) in the tag.

Example

use id3::{Tag, TagLike};
use id3::frame::{Chapter, TableOfContents, Content, Frame};

let mut tag = Tag::new();
tag.add_frame(Chapter{
    element_id: "chap01".to_string(),
    start_time: 1000,
    end_time: 2000,
    start_offset: 0xff,
    end_offset: 0xff,
    frames: Vec::new(),
});
tag.add_frame(TableOfContents{
    element_id: "internalTable01".to_string(),
    top_level: false,
    ordered: false,
    elements: Vec::new(),
    frames: Vec::new(),
});
tag.add_frame(TableOfContents{
    element_id: "01".to_string(),
    top_level: true,
    ordered: true,
    elements: vec!["internalTable01".to_string(),"chap01".to_string()],
    frames: Vec::new(),
});
assert_eq!(2, tag.tables_of_contents().count());

pub fn involved_people_lists(&self) -> impl Iterator<Item = &InvolvedPeopleList>

Returns an iterator over all involved people lists (IPLS in ID3v2.3, TIPL and TMCL in ID3v2.4) in the tag.

Examples

IPLS frame (ID3v2.3)

use id3::{Frame, Tag, TagLike, Version};
use id3::frame::{Content, InvolvedPeopleList, InvolvedPeopleListItem};

let mut tag = Tag::with_version(Version::Id3v23);

let frame = Frame::with_content("IPLS", Content::InvolvedPeopleList(InvolvedPeopleList {
    items: vec![
        InvolvedPeopleListItem {
            involvement: "drums (drum set)".to_string(),
            involvee: "Gene Krupa".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "piano".to_string(),
            involvee: "Hank Jones".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "tenor saxophone".to_string(),
            involvee: "Frank Socolow".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "tenor saxophone".to_string(),
            involvee: "Eddie Wasserman".to_string(),
        },
    ],
}));
tag.add_frame(frame);
assert_eq!(1, tag.involved_people_lists().count());
assert_eq!(4, tag.involved_people_lists().flat_map(|list| list.items.iter()).count());

TIPL/TMCL frames (ID3v2.4)

use id3::{Frame, Tag, TagLike, Version};
use id3::frame::{Content, InvolvedPeopleList, InvolvedPeopleListItem};

let mut tag = Tag::with_version(Version::Id3v24);

let frame = Frame::with_content("TMCL", Content::InvolvedPeopleList(InvolvedPeopleList {
    items: vec![
        InvolvedPeopleListItem {
            involvement: "drums (drum set)".to_string(),
            involvee: "Gene Krupa".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "piano".to_string(),
            involvee: "Hank Jones".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "tenor saxophone".to_string(),
            involvee: "Frank Socolow".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "tenor saxophone".to_string(),
            involvee: "Eddie Wasserman".to_string(),
        },
    ],
}));
tag.add_frame(frame);

let frame = Frame::with_content("TIPL", Content::InvolvedPeopleList(InvolvedPeopleList {
    items: vec![
        InvolvedPeopleListItem {
            involvement: "executive producer".to_string(),
            involvee: "Ken Druker".to_string(),
        },
        InvolvedPeopleListItem {
            involvement: "arranger".to_string(),
            involvee: "Gerry Mulligan".to_string(),
        },
    ],
}));
tag.add_frame(frame);
assert_eq!(2, tag.involved_people_lists().count());
assert_eq!(6, tag.involved_people_lists().flat_map(|list| list.items.iter()).count());

Trait Implementations

impl Clone for Tag

fn clone(&self) -> Tag

Returns a copy of the value.

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

Performs copy-assignment from source.

impl Debug for Tag

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

Formats the value using the given formatter.

impl Default for Tag

fn default() -> Tag

Returns the “default value” for a type.

impl Extend<Frame> for Tag

fn extend<I: IntoIterator<Item = Frame>>(&mut self, iter: I)

Extends a collection with the contents of an iterator.

fn extend_one(&mut self, item: A)

🔬This is a nightly-only experimental API. (extend_one)

Extends a collection with exactly one element.

fn extend_reserve(&mut self, additional: usize)

🔬This is a nightly-only experimental API. (extend_one)

Reserves capacity in a collection for the given number of additional elements.

impl From<Tag> for Tag

fn from(tag_v1: Tag) -> Tag

Converts to this type from the input type.

impl FromIterator<Frame> for Tag

fn from_iter<I: IntoIterator<Item = Frame>>(iter: I) -> Self

Creates a value from an iterator.

impl PartialEq for Tag

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

Tests for self and other values to be equal, and is used by ==.

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

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

impl TagLike for Tag

fn get(&self, id: impl AsRef<str>) -> Option<&Frame>

Returns a reference to the first frame with the specified identifier.

fn add_frame(&mut self, new_frame: impl Into<Frame>) -> Option<Frame>

Adds the frame to the tag, replacing and returning any conflicting frame.

fn set_text(&mut self, id: impl AsRef<str>, text: impl Into<String>)

Adds a text frame.

fn set_text_values( &mut self, id: impl AsRef<str>, texts: impl IntoIterator<Item = impl Into<String>>, )

Panics

fn remove(&mut self, id: impl AsRef<str>) -> Vec<Frame>

Remove all frames with the specified identifier and return them.

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

Returns the year (TYER). Returns None if the year frame could not be found or if it could not be parsed.

fn set_year(&mut self, year: i32)

Sets the year (TYER).

fn remove_year(&mut self)

Removes the year (TYER).

fn date_recorded(&self) -> Option<Timestamp>

Return the content of the TDRC frame, if any

fn set_date_recorded(&mut self, timestamp: Timestamp)

Sets the content of the TDRC frame

fn remove_date_recorded(&mut self)

Remove the content of the TDRC frame

fn date_released(&self) -> Option<Timestamp>

Return the content of the TDRL frame, if any

fn set_date_released(&mut self, timestamp: Timestamp)

Sets the content of the TDRL frame

fn remove_date_released(&mut self)

Remove the content of the TDRL frame

fn original_date_released(&self) -> Option<Timestamp>

Return the content of the TDOR frame, if any

fn set_original_date_released(&mut self, timestamp: Timestamp)

Sets the content of the TDOR frame

fn remove_original_date_released(&mut self)

Remove the content of the TDOR frame

fn artist(&self) -> Option<&str>

Returns the artist (TPE1).

fn artists(&self) -> Option<Vec<&str>>

Returns the (potential) multiple artists (TPE1).

fn set_artist(&mut self, artist: impl Into<String>)

Sets the artist (TPE1).

fn remove_artist(&mut self)

Removes the artist (TPE1).

fn album_artist(&self) -> Option<&str>

Sets the album artist (TPE2).

fn set_album_artist(&mut self, album_artist: impl Into<String>)

Sets the album artist (TPE2).

fn remove_album_artist(&mut self)

Removes the album artist (TPE2).

fn album(&self) -> Option<&str>

Returns the album (TALB).

fn set_album(&mut self, album: impl Into<String>)

Sets the album (TALB).

fn remove_album(&mut self)

Removes the album (TALB).

fn title(&self) -> Option<&str>

Returns the title (TIT2).

fn set_title(&mut self, title: impl Into<String>)

Sets the title (TIT2).

fn remove_title(&mut self)

Removes the title (TIT2).

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

Returns the duration (TLEN).

fn set_duration(&mut self, duration: u32)

Sets the duration (TLEN).

fn remove_duration(&mut self)

Removes the duration (TLEN).

fn genre(&self) -> Option<&str>

Returns the plain genre (TCON) text.

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

Returns the genre (TCON) with ID3v1 genre indices resolved.

fn genres(&self) -> Option<Vec<&str>>

Returns the (potential) multiple plain genres (TCON).

fn set_genre(&mut self, genre: impl Into<String>)

Sets the plain genre (TCON).

fn remove_genre(&mut self)

Removes the genre (TCON).

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

Returns the disc number (TPOS).

fn set_disc(&mut self, disc: u32)

Sets the disc (TPOS).

fn remove_disc(&mut self)

Removes the disc number (TPOS).

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

Returns the total number of discs (TPOS).

fn set_total_discs(&mut self, total_discs: u32)

Sets the total number of discs (TPOS).

fn remove_total_discs(&mut self)

Removes the total number of discs (TPOS).

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

Returns the track number (TRCK).

fn set_track(&mut self, track: u32)

Sets the track (TRCK).

fn remove_track(&mut self)

Removes the track number (TRCK).

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

Returns the total number of tracks (TRCK).

fn set_total_tracks(&mut self, total_tracks: u32)

Sets the total number of tracks (TRCK).

fn remove_total_tracks(&mut self)

Removes the total number of tracks (TCON).

fn add_extended_text( &mut self, description: impl Into<String>, value: impl Into<String>, )

👎Deprecated: Use add_frame(frame::ExtendedText{ .. })

Adds a user defined text frame (TXXX).

fn remove_extended_text( &mut self, description: Option<&str>, value: Option<&str>, )

Removes the user defined text frame (TXXX) with the specified key and value.

fn add_picture(&mut self, picture: Picture)

👎Deprecated: Use add_frame(frame::Picture{ .. })

Adds a picture frame (APIC). Any other pictures with the same type will be removed from the tag.

fn remove_picture_by_type(&mut self, picture_type: PictureType)

Removes all pictures of the specified type.

fn remove_all_pictures(&mut self)

Removes all pictures.

fn add_comment(&mut self, comment: Comment)

👎Deprecated: Use add_frame(frame::Comment{ .. })

Adds a comment (COMM).

fn remove_comment(&mut self, description: Option<&str>, text: Option<&str>)

Removes the comment (COMM) with the specified key and value.

fn add_encapsulated_object( &mut self, description: impl Into<String>, mime_type: impl Into<String>, filename: impl Into<String>, data: impl Into<Vec<u8>>, )

👎Deprecated: Use add_frame(frame::EncapsulatedObject{ .. })

Adds an encapsulated object frame (GEOB).

fn remove_encapsulated_object( &mut self, description: Option<&str>, mime_type: Option<&str>, filename: Option<&str>, data: Option<&[u8]>, )

Removes the encapsulated object frame (GEOB) with the specified key, MIME type, filename and data.

fn add_lyrics(&mut self, lyrics: Lyrics)

👎Deprecated: Use add_frame(frame::Lyrics{ .. })

Sets the lyrics (USLT).

fn remove_all_lyrics(&mut self)

Removes the lyrics text (USLT) from the tag.

fn add_synchronised_lyrics(&mut self, lyrics: SynchronisedLyrics)

👎Deprecated: Use add_frame(frame::SynchronisedLyrics{ .. })

Adds a synchronised lyrics frame (SYLT).

fn remove_all_synchronised_lyrics(&mut self)

Removes all synchronised lyrics (SYLT) frames from the tag.

fn remove_all_chapters(&mut self)

/// Removes all chapters (CHAP) frames from the tag.

fn remove_all_tables_of_contents(&mut self)

/// Removes all tables of contents (CTOC) frames from the tag.

fn remove_unique_file_identifier_by_owner_identifier( &mut self, owner_identifier: &str, )

Removes all Unique File Identifiers with the specified owner_identifier.

fn remove_all_unique_file_identifiers(&mut self)

Removes all unique file identifiers.

impl Eq for Tag