Struct id3::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: &mut File) -> 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>

Attempts to read an ID3 tag from the reader.

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>

Reads an AIFF stream and returns any present ID3 tag.

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

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

pub fn read_from_aiff_file(file: &mut File) -> Result<Tag>

Reads an AIFF file and returns any present ID3 tag.

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

Reads an WAV stream and returns any present ID3 tag.

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

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

pub fn read_from_wav_file(file: &mut File) -> Result<Tag>

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_path.

pub fn write_to_path(
    &self,
    path: impl AsRef<Path>,
    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_aiff_path(
    &self,
    path: impl AsRef<Path>,
    version: Version
) -> Result<()>

Overwrite WAV file ID3 chunk in a file

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

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

Overwrite WAV file ID3 chunk

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

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

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<Tag> for Tag

fn eq(&self, other: &Tag) -> 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 !=.

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 TRDC 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 artist(&self) -> Option<&str>

Returns the artist (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 genre (TCON).

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

Sets the 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)

Adds a single chapter (CHAP) to the farme.

impl Eq for Tag

impl StructuralEq for Tag