Struct lofty::mp4::Ilst

source ·

pub struct Ilst { /* private fields */ }

Expand description

An MP4 ilst atom

§Supported file types

FileType::Mp4

§Pictures

Unlike other formats, ilst does not store a PictureType. All pictures will have PictureType::Other.

§Conversions

§To `Tag`

When converting to Tag, only atoms with a value of AtomData::UTF8 and AtomData::UTF16, with the exception of the trkn and disk atoms, as well as pictures, will be preserved.

Do note, all pictures will be PictureType::Other

§From `Tag`

When converting from Tag, only items with a value of ItemValue::Text, as well as pictures, will be preserved.

An attempt will be made to create the TrackNumber/TrackTotal (trkn) and DiscNumber/DiscTotal (disk) pairs.

Implementations§

source §

impl Ilst

source

pub fn new() -> Self

Create a new empty Ilst

§Examples

use lofty::mp4::Ilst;
use lofty::tag::TagExt;

let ilst_tag = Ilst::new();
assert!(ilst_tag.is_empty());

source

pub fn get(&self, ident: &AtomIdent<'_>) -> Option<&Atom<'static>>

Get an item by its AtomIdent

§Examples

use lofty::mp4::{AtomIdent, Ilst};
use lofty::tag::Accessor;

let mut ilst = Ilst::new();
ilst.set_title(String::from("Foo title"));

// Get the title by its FOURCC identifier
let title = ilst.get(&AtomIdent::Fourcc(*b"\xa9nam"));
assert!(title.is_some());

source

pub fn insert(&mut self, atom: Atom<'static>)

Inserts an Atom

NOTE: Do not use this to replace atoms. This will take the value from the provided atom and merge it into an atom of the same type, keeping any existing value(s). To ensure an atom is replaced, use Ilst::replace_atom.

§Examples

use lofty::mp4::{Atom, AtomData, AtomIdent, Ilst};

const TITLE_IDENTIFIER: AtomIdent = AtomIdent::Fourcc(*b"\xa9nam");

let mut ilst = Ilst::new();

// Set the title by manually constructing an `Atom`
let title_atom = Atom::new(TITLE_IDENTIFIER, AtomData::UTF8(String::from("Foo title")));
ilst.insert(title_atom);

// Get the title by its FOURCC identifier
let title = ilst.get(&TITLE_IDENTIFIER);
assert!(title.is_some());

source

pub fn replace_atom(&mut self, atom: Atom<'_>)

Inserts an Atom, replacing any atom with the same AtomIdent

§Examples

use lofty::mp4::{Atom, AtomData, AtomIdent, Ilst};
use lofty::tag::Accessor;

const TITLE_IDENTIFIER: AtomIdent = AtomIdent::Fourcc(*b"\xa9nam");

let mut ilst = Ilst::new();

ilst.set_title(String::from("FooBar"));
assert_eq!(ilst.title().as_deref(), Some("FooBar"));

// Replace our old title
ilst.replace_atom(Atom::new(
	TITLE_IDENTIFIER,
	AtomData::UTF8(String::from("BarFoo")),
));
assert_eq!(ilst.title().as_deref(), Some("BarFoo"));

source

pub fn remove( &mut self, ident: &AtomIdent<'_>, ) -> impl Iterator<Item = Atom<'static>> + '_

Remove an atom by its AtomIdent

§Examples

use lofty::mp4::{Atom, AtomData, AtomIdent, Ilst};
use lofty::tag::Accessor;

const TITLE_IDENTIFIER: AtomIdent = AtomIdent::Fourcc(*b"\xa9nam");

let mut ilst = Ilst::new();
ilst.set_title(String::from("Foo title"));

// Get the title by its FOURCC identifier
let title = ilst.get(&TITLE_IDENTIFIER);
assert!(title.is_some());

// Remove the title
let returned = ilst.remove(&TITLE_IDENTIFIER);
assert_eq!(returned.count(), 1);

let title = ilst.get(&TITLE_IDENTIFIER);
assert!(title.is_none());

source

pub fn retain<F>(&mut self, f: F)
where F: FnMut(&Atom<'_>) -> bool,

Retain atoms based on the predicate

See Vec::retain

source

pub fn pictures(&self) -> Option<impl Iterator<Item = &Picture>>

Returns all pictures, if there are any

§Examples

use lofty::mp4::Ilst;
use lofty::picture::{MimeType, Picture, PictureType};
use lofty::tag::TagExt;

let mut ilst = Ilst::new();

// Insert pictures
ilst.insert_picture(Picture::new_unchecked(
	PictureType::Other,
	Some(MimeType::Png),
	None,
	png_data,
));

ilst.insert_picture(Picture::new_unchecked(
	PictureType::Other,
	Some(MimeType::Jpeg),
	None,
	jpeg_data,
));

assert_eq!(ilst.pictures().unwrap().count(), 2);

source

pub fn insert_picture(&mut self, picture: Picture)

Inserts a picture

NOTE: If a covr atom exists in the tag, the picture will be appended to it.

§Examples

use lofty::mp4::Ilst;
use lofty::picture::{MimeType, Picture, PictureType};
use lofty::tag::TagExt;

let mut ilst = Ilst::new();

// Insert a single picture
ilst.insert_picture(Picture::new_unchecked(
	PictureType::Other,
	Some(MimeType::Png),
	None,
	png_data,
));
assert_eq!(ilst.len(), 1);

// Insert another picture
ilst.insert_picture(Picture::new_unchecked(
	PictureType::Other,
	Some(MimeType::Jpeg),
	None,
	jpeg_data,
));

// The existing `covr` atom is reused
assert_eq!(ilst.len(), 1);
assert_eq!(ilst.pictures().unwrap().count(), 2);