Enum Tag

pub enum Tag {
    Id3Tag {
        inner: Tag,
    },
    VorbisFlacTag {
        inner: Tag,
    },
    Mp4Tag {
        inner: Tag,
    },
    OpusTag {
        inner: Tag,
    },
}

An object containing tags of one of the supported formats.

Variants

Id3Tag

Fields

inner: Tag

VorbisFlacTag

Fields

inner: Tag

Mp4Tag

Fields

inner: Tag

OpusTag

Fields

inner: Tag

Implementations

impl Tag

pub fn read_from_path<P: AsRef<Path>>(path: P) -> Result<Self>

Attempts to read a set of tags from the given path.

Errors

This function could error if the given path has a file extension which contains invalid unicode or if the given path does not have a file extension at all.

This function could also error if the given path has a valid extension but the extension is not among the types supported by this crate.

Lastly, an error will be raised if the file type is supported but the reading the tags fails for some reason other than missing tags.

Examples found in repository

examples/read_tag.rs (line 12)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());

    // Option 1: read from path
    let tag = Tag::read_from_path(&path).unwrap();
    println!("{:#?}", tag.title());

    // Option 2: read from reader
    let mut f = File::open(&path).unwrap();

    let mut data = Vec::new();
    f.read_to_end(&mut data).unwrap();

    let cursor = Cursor::new(data);
    // You can also just pass in f instead of creating a cursor since Files are Read + Seek
    let extension = path.extension().unwrap().to_str().unwrap();
    let tag = Tag::read_from(extension, cursor).unwrap();
    println!("{:#?}", tag.title());
}

pub fn read_from<R: Read + Seek>(extension: &str, f_in: R) -> Result<Self>

Attempts to read a set of tags from the given reader. The extension is necessary to determine which backend to use to decode the tags. extension must be one of [mp3, wav, aiff, flac, mp4, m4a, m4p, m4b, m4r, m4v, opus]

Errors

This function can error if the given extension is not supported by this crate.

Lastly, an error will be raised if the file type is supported but the reading the tags fails for some reason other than missing tags. This could be, for example, that the given reader ended too early or that the tags were encoded improperly. Please inspect the debug output of the error for more information.

Examples found in repository

examples/edit_tag.rs (line 19)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut tag = Tag::read_from(extension, &file).unwrap();

    file.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_file(&mut file).unwrap();
}

examples/read_tag.rs (line 24)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());

    // Option 1: read from path
    let tag = Tag::read_from_path(&path).unwrap();
    println!("{:#?}", tag.title());

    // Option 2: read from reader
    let mut f = File::open(&path).unwrap();

    let mut data = Vec::new();
    f.read_to_end(&mut data).unwrap();

    let cursor = Cursor::new(data);
    // You can also just pass in f instead of creating a cursor since Files are Read + Seek
    let extension = path.extension().unwrap().to_str().unwrap();
    let tag = Tag::read_from(extension, cursor).unwrap();
    println!("{:#?}", tag.title());
}

examples/edit_tag_vec.rs (line 25)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut data = Vec::new();
    file.read_to_end(&mut data).unwrap();
    let mut cursor = Cursor::new(&mut data);

    let mut tag = Tag::read_from(extension, &mut cursor).unwrap();

    cursor.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_vec(&mut data).unwrap();

    file.rewind().unwrap();
    file.write_all(&data).unwrap();
}

pub fn write_to_path<P: AsRef<Path>>(&mut self, path: P) -> Result<()>

Attempts to write the tags to the indicated path.

Errors

This function will error if writing the tags fails in any way.

pub fn write_to_file(&mut self, file: &mut File) -> Result<()>

Write to a file. The file should already contain valid data of the correct type (e.g. the file should already contain an opus stream in order to correctly write opus tags).

The file’s cursor should be at the beginning of the file, and it should be opened with read and write modes set (See OpenOptions for more info).

Errors

This method can error if writing the tags fails, or if accessing the file fails (for example, if the modes are set wrong).

Examples found in repository

examples/edit_tag.rs (line 26)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut tag = Tag::read_from(extension, &file).unwrap();

    file.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_file(&mut file).unwrap();
}

pub fn write_to_vec(&mut self, vec: &mut Vec<u8>) -> Result<()>

Write to a byte vector. The vector should already contain valid data of the correct type (e.g. the vector should already contain an opus stream in order to correctly write opus tags).

Errors

This method can error if one of the internal write methods fails. If that happens, the inner error will contain more information.

Examples found in repository

examples/edit_tag_vec.rs (line 32)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut data = Vec::new();
    file.read_to_end(&mut data).unwrap();
    let mut cursor = Cursor::new(&mut data);

    let mut tag = Tag::read_from(extension, &mut cursor).unwrap();

    cursor.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_vec(&mut data).unwrap();

    file.rewind().unwrap();
    file.write_all(&data).unwrap();
}

pub fn new_empty_id3() -> Self

Creates an empty set of tags in the ID3 format.

pub fn new_empty_flac() -> Self

Creates an empty set of tags in the FLAC format.

pub fn new_empty_mp4() -> Self

Creates an empty set of tags in the MP4 format.

pub fn new_empty_opus() -> Self

Creates an empty set of tags in the Opus format.

impl Tag

pub fn get_album_info(&self) -> Option<Album>

Gets the album information. If the album or album_artist fields are not present in the audio file, this method returns None.

pub fn set_album_info(&mut self, album: Album) -> Result<()>

Sets the album information of the audio track.

Errors

This function will error if album.cover has an invalid or unsupported MIME type. Supported MIME types are: image/bmp, image/jpeg, image/png

pub fn remove_all_album_info(&mut self)

Removes all album infofrom the audio track.

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

Gets the title.

Examples found in repository

examples/read_tag.rs (line 13)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());

    // Option 1: read from path
    let tag = Tag::read_from_path(&path).unwrap();
    println!("{:#?}", tag.title());

    // Option 2: read from reader
    let mut f = File::open(&path).unwrap();

    let mut data = Vec::new();
    f.read_to_end(&mut data).unwrap();

    let cursor = Cursor::new(data);
    // You can also just pass in f instead of creating a cursor since Files are Read + Seek
    let extension = path.extension().unwrap().to_str().unwrap();
    let tag = Tag::read_from(extension, cursor).unwrap();
    println!("{:#?}", tag.title());
}

pub fn set_title(&mut self, title: &str)

Sets the title.

Examples found in repository

examples/edit_tag.rs (line 25)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut tag = Tag::read_from(extension, &file).unwrap();

    file.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_file(&mut file).unwrap();
}

examples/edit_tag_vec.rs (line 31)

fn main() {
    let path = PathBuf::from(args().nth(1).unwrap());
    let mut file = OpenOptions::new()
        .read(true)
        .write(true)
        // .truncate(true)
        .open(&path)
        .unwrap();

    let extension = path.extension().unwrap().to_str().unwrap();

    let mut data = Vec::new();
    file.read_to_end(&mut data).unwrap();
    let mut cursor = Cursor::new(&mut data);

    let mut tag = Tag::read_from(extension, &mut cursor).unwrap();

    cursor.rewind().unwrap();

    let title = args().skip(2).collect::<Vec<String>>().join(" ");

    tag.set_title(&title);
    tag.write_to_vec(&mut data).unwrap();

    file.rewind().unwrap();
    file.write_all(&data).unwrap();
}

pub fn remove_title(&mut self)

Removes any title fields from the file.

pub fn artist(&self) -> Option<String>

Gets the artist (note: NOT the album artist!) If multiple ARTIST tags are present, they will be joined with a ;

pub fn set_artist(&mut self, artist: &str)

Sets the artist (note: NOT the album artist!)

pub fn remove_artist(&mut self)

Removes the artist (note: NOT the album artist!)

pub fn date(&self) -> Option<Timestamp>

Gets the date

Format-specific

In id3, this method corresponds to the date_released field.

pub fn set_date(&mut self, timestamp: Timestamp)

Sets the date

Format-specific

In id3, this method corresponds to the date_released field.

pub fn remove_date(&mut self)

Removes the date

Format-specific

In id3, this method corresponds to the date_released field.

pub fn copy_to(&self, other: &mut Self)

Copies the information of this Tag to another. The target Tag can be any of the supported formats.