lofty/lib.rs
1//! [](https://github.com/Serial-ATA/lofty-rs/actions/workflows/ci.yml)
2//! [](https://crates.io/crates/lofty)
3//! [](https://crates.io/crates/lofty)
4//!
5//! Parse, convert, and write metadata to audio formats.
6//!
7//! # Supported Formats
8#![doc = include_str!("../SUPPORTED_FORMATS.md")]
9//! # Examples
10//!
11//! ## Reading a generic file
12//!
13//! It isn't always convenient to [use concrete file types](#using-concrete-file-types), which is where [`TaggedFile`](file::TaggedFile)
14//! comes in.
15//!
16//! ### Using a path
17//!
18//! ```rust,no_run
19//! # fn main() -> lofty::error::Result<()> {
20//! use lofty::probe::Probe;
21//! use lofty::read_from_path;
22//!
23//! // This will guess the format from the extension
24//! // ("mp3" in this case), but we can guess from the content if we want to.
25//! let path = "test.mp3";
26//! let tagged_file = read_from_path(path)?;
27//!
28//! // Let's guess the format from the content just in case.
29//! // This is not necessary in this case!
30//! let tagged_file2 = Probe::open(path)?.guess_file_type()?.read()?;
31//! # Ok(())
32//! # }
33//! ```
34//!
35//! ### Using an existing reader
36//!
37//! ```rust,no_run
38//! # fn main() -> lofty::error::Result<()> {
39//! use lofty::config::ParseOptions;
40//! use lofty::read_from;
41//! use std::fs::File;
42//!
43//! // Let's read from an open file
44//! let path = "test.mp3";
45//! let mut file = File::open(path)?;
46//!
47//! // Here, we have to guess the file type prior to reading
48//! let tagged_file = read_from(&mut file)?;
49//! # Ok(())
50//! # }
51//! ```
52//!
53//! ### Accessing tags
54//!
55//! ```rust,no_run
56//! # fn main() -> lofty::error::Result<()> {
57//! use lofty::file::TaggedFileExt;
58//! use lofty::read_from_path;
59//!
60//! let path = "test.mp3";
61//! let tagged_file = read_from_path(path)?;
62//!
63//! // Get the primary tag (ID3v2 in this case)
64//! let id3v2 = tagged_file.primary_tag();
65//!
66//! // If the primary tag doesn't exist, or the tag types
67//! // don't matter, the first tag can be retrieved
68//! let unknown_first_tag = tagged_file.first_tag();
69//! # Ok(())
70//! # }
71//! ```
72//!
73//! ## Using concrete file types
74//!
75//! ```rust
76//! # fn main() -> lofty::error::Result<()> {
77//! use lofty::config::ParseOptions;
78//! use lofty::file::AudioFile;
79//! use lofty::mpeg::MpegFile;
80//! use lofty::tag::TagType;
81//! use std::fs::File;
82//!
83//! # let path = "tests/files/assets/minimal/full_test.mp3";
84//! let mut file_content = File::open(path)?;
85//!
86//! // We are expecting an MP3 file
87//! let mp3_file = MpegFile::read_from(&mut file_content, ParseOptions::new())?;
88//!
89//! assert_eq!(mp3_file.properties().channels(), 2);
90//!
91//! // Here we have a file with multiple tags
92//! assert!(mp3_file.contains_tag_type(TagType::Id3v2));
93//! assert!(mp3_file.contains_tag_type(TagType::Ape));
94//! # Ok(())
95//! # }
96//! ```
97//!
98//! # Important format-specific notes
99//!
100//! All formats have their own quirks that may produce unexpected results between conversions.
101//! Be sure to read the module documentation of each format to see important notes and warnings.
102#![cfg_attr(docsrs, feature(doc_auto_cfg))]
103#![doc(html_logo_url = "https://raw.githubusercontent.com/Serial-ATA/lofty-rs/main/doc/lofty.svg")]
104
105// proc macro hacks
106extern crate self as lofty;
107pub(crate) mod _this_is_internal {}
108
109pub mod config;
110pub mod error;
111pub mod file;
112pub(crate) mod macros;
113pub mod picture;
114pub mod probe;
115pub mod properties;
116pub mod resolve;
117pub mod tag;
118mod util;
119
120pub mod aac;
121pub mod ape;
122pub mod flac;
123pub mod id3;
124pub mod iff;
125pub mod mp4;
126pub mod mpeg;
127pub mod musepack;
128pub mod ogg;
129pub mod wavpack;
130
131pub use crate::probe::{read_from, read_from_path};
132
133pub use util::text::TextEncoding;
134
135pub use lofty_attr::LoftyFile;
136
137pub use util::io;
138
139pub mod prelude {
140 //! A prelude for commonly used items in the library.
141 //!
142 //! This module is intended to be wildcard imported.
143 //!
144 //! ```rust
145 //! use lofty::prelude::*;
146 //! ```
147
148 pub use crate::file::{AudioFile, TaggedFileExt};
149 pub use crate::tag::{Accessor, ItemKey, MergeTag, SplitTag, TagExt};
150}