Struct Tag

pub struct Tag { /* private fields */ }

Stores Opus comments.

Implementations

impl Tag

pub fn new(vendor: String, comments: Vec<(String, String)>) -> Self

Create a new tag from a vendor string and a list of comments.

pub fn add_one(&mut self, tag: String, value: String)

Add one entry.

pub fn add_many(&mut self, tag: String, values: Vec<String>)

Add multiple entries.

pub fn get(&self, tag: String) -> Option<&Vec<String>>

Get all entries for a particular key, or None if no occurrences of the key exist.

pub fn get_one(&self, tag: String) -> Option<&String>

Gets the first entry for a particular key, or None if no occurences of the key exist.

pub fn remove_entries(&mut self, tag: String) -> Option<Vec<String>>

Remove all entries for a particular key. Optionally returns the removed values, if any.

pub fn get_vendor(&self) -> &str

Gets the vendor string

pub fn set_vendor(&mut self, new_vendor: String)

Sets the vendor string.

pub fn add_picture(&mut self, picture: &Picture) -> Result<()>

Add a picture. If a picture with the same PictureType already exists, it is removed first.

Errors

This function will error if remove_picture_type errors, or if encoding the given data to Opus format or to base64 errors.

pub fn remove_picture_type( &mut self, picture_type: PictureType, ) -> Result<Option<Picture>>

Removes a picture with the given picture type. Returns the removed picture for convenience.

Errors

Although rare, this function can error if a picture with the given type is not found AND the first picture in the set is not decoded properly.

pub fn get_picture_type(&self, picture_type: PictureType) -> Option<Picture>

Gets a picture which has a certain picture type, or None if there are no pictures with that type.

pub fn pictures(&self) -> Vec<Picture>

Returns a Vec of all encoded pictures. This function will skip pictures that are encoded improperly.

impl Tag

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

Read a Tag from a reader.

Errors

This function can error if:

• The ogg stream is shorter than expected (e.g. doesn’t include the first or second packets)
• The given reader is not an opus stream
• The comment header does not include the magic signature
• The comment header is shorter than mandated by the spec
• The platform’s usize is not at least 32 bits long
• The spec mandates UTF-8, but the data is invalid unicode
• A comment line is not in TAG=VALUE format.

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

Convenience function for reading comments from a path.

Errors

This function will error for the same reasons as read_from

pub fn write_to<W: Read + Write + Seek>(&self, f_in: W) -> Result<()>

Writes tags to a writer. This function expects the writer to already contain an existing opus stream. This function reads the existing stream, copies it into memory, replaces the comment header, and dumps the whole stream back into the file.

Errors

This function will error if:

• No opus stream exists in the target
• The ogg stream is shorter than expected (e.g. doesn’t include the first or second packets)
• A comment in this Tag object is too big for the opus spec (some string is longer than u32::MAX bytes, or the object contains more than u32::MAX comments)
• An unspecified error occurs while reading ogg packets from the target
• An error occurs while writing an ogg packet to the target
• An error occurs while seeking through the target
• An error occurs while copying the finished ogg stream from memory back to the target

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

Convenience function for writing to a path.

Errors

This function will error for the same reasons as write_to

Trait Implementations

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.