Skip to main content

file_format/
lib.rs

1/*!
2Crate for determining the file format of a [given file](`FileFormat::from_file`) or stream.
3
4It provides a variety of functions for identifying a wide range of file formats, including
5[ZIP](`FileFormat::Zip`), [Compound File Binary (CFB)](`FileFormat::CompoundFileBinary`),
6[Extensible Markup Language (XML)](`FileFormat::ExtensibleMarkupLanguage`) and [more](`FileFormat`).
7
8It checks the signature of the file to determine its format and intelligently employs specific
9readers when available for accurate identification. If the signature is not recognized, the crate
10falls back to the [default](`FileFormat::default`) file format, which is
11[Arbitrary Binary Data (BIN)](`FileFormat::ArbitraryBinaryData`).
12
13# Examples
14
15Determines from a file:
16
17```no_run
18use file_format::{FileFormat, Kind};
19
20let fmt = FileFormat::from_file("fixtures/document/sample.pdf")?;
21assert_eq!(fmt, FileFormat::PortableDocumentFormat);
22assert_eq!(fmt.name(), "Portable Document Format");
23assert_eq!(fmt.short_name(), Some("PDF"));
24assert_eq!(fmt.media_type(), "application/pdf");
25assert_eq!(fmt.extension(), "pdf");
26assert_eq!(fmt.kind(), Kind::Document);
27# Ok::<(), std::io::Error>(())
28```
29
30Determines from bytes:
31
32```
33use file_format::{FileFormat, Kind};
34
35let fmt = FileFormat::from_bytes(&[0xFF, 0xD8, 0xFF]);
36assert_eq!(fmt, FileFormat::JointPhotographicExpertsGroup);
37assert_eq!(fmt.name(), "Joint Photographic Experts Group");
38assert_eq!(fmt.short_name(), Some("JPEG"));
39assert_eq!(fmt.media_type(), "image/jpeg");
40assert_eq!(fmt.extension(), "jpg");
41assert_eq!(fmt.kind(), Kind::Image);
42```
43
44Retrieves file formats by extension, media type, or kind:
45
46```
47use file_format::{FileFormat, Kind};
48
49let formats = FileFormat::from_extension("jpg");
50assert!(formats.contains(&FileFormat::JointPhotographicExpertsGroup));
51
52let formats = FileFormat::from_media_type("image/jpeg");
53assert!(formats.contains(&FileFormat::JointPhotographicExpertsGroup));
54
55let formats = FileFormat::from_kind(Kind::Image);
56assert!(formats.contains(&FileFormat::JointPhotographicExpertsGroup));
57```
58
59# Crate features
60
61All features below are disabled by default.
62
63## Reader features
64
65These features enable the detection of file formats that require a specific reader for
66identification.
67
68- `reader` - Enables all reader features.
69- `reader-asf` - Enables [Advanced Systems Format (ASF)](`FileFormat::AdvancedSystemsFormat`) based
70  file formats detection.
71  * [Microsoft Digital Video Recording (DVR-MS)](`FileFormat::MicrosoftDigitalVideoRecording`)
72  * [Windows Media Audio (WMA)](`FileFormat::WindowsMediaAudio`)
73  * [Windows Media Video (WMV)](`FileFormat::WindowsMediaVideo`)
74- `reader-cfb` - Enables [Compound File Binary (CFB)](`FileFormat::CompoundFileBinary`) based file
75  formats detection.
76  * [3D Studio Max (MAX)](`FileFormat::ThreeDimensionalStudioMax`)
77  * [Autodesk Inventor Assembly (IAM)](`FileFormat::AutodeskInventorAssembly`)
78  * [Autodesk Inventor Drawing (IDW)](`FileFormat::AutodeskInventorDrawing`)
79  * [Autodesk Inventor Part (IPT)](`FileFormat::AutodeskInventorPart`)
80  * [Autodesk Inventor Presentation (IPN)](`FileFormat::AutodeskInventorPresentation`)
81  * [Corel Presentations 7 (SHW)](`FileFormat::CorelPresentations7`)
82  * [Flash Project (FLA)](`FileFormat::FlashProject`)
83  * [Microsoft Excel Spreadsheet (XLS)](`FileFormat::MicrosoftExcelSpreadsheet`)
84  * [Microsoft PowerPoint Presentation (PPT)](`FileFormat::MicrosoftPowerpointPresentation`)
85  * [Microsoft Project Plan (MPP)](`FileFormat::MicrosoftProjectPlan`)
86  * [Microsoft Publisher Document (PUB)](`FileFormat::MicrosoftPublisherDocument`)
87  * [Microsoft Software Installer (MSI)](`FileFormat::MicrosoftSoftwareInstaller`)
88  * [Microsoft Visio Drawing (VSD)](`FileFormat::MicrosoftVisioDrawing`)
89  * [Microsoft Word Document (DOC)](`FileFormat::MicrosoftWordDocument`)
90  * [Microsoft Works 6 Spreadsheet (XLR)](`FileFormat::MicrosoftWorks6Spreadsheet`)
91  * [Microsoft Works Database (WDB)](`FileFormat::MicrosoftWorksDatabase`)
92  * [Microsoft Works Word Processor (WPS)](`FileFormat::MicrosoftWorksWordProcessor`)
93  * [SolidWorks Assembly (SLDASM)](`FileFormat::SolidworksAssembly`)
94  * [SolidWorks Drawing (SLDDRW)](`FileFormat::SolidworksDrawing`)
95  * [SolidWorks Part (SLDPRT)](`FileFormat::SolidworksPart`)
96  * [StarCalc (SDC)](`FileFormat::Starcalc`)
97  * [StarChart (SDS)](`FileFormat::Starchart`)
98  * [StarDraw (SDA)](`FileFormat::Stardraw`)
99  * [StarImpress (SDD)](`FileFormat::Starimpress`)
100  * [StarMath (SMF)](`FileFormat::Starmath`)
101  * [StarWriter (SDW)](`FileFormat::Starwriter`)
102  * [WordPerfect Document (WPD)](`FileFormat::WordperfectDocument`)
103  * [WordPerfect Graphics (WPG)](`FileFormat::WordperfectGraphics`)
104- `reader-ebml` - Enables [Extensible Binary Meta Language (EBML)](`FileFormat::ExtensibleBinaryMetaLanguage`)
105  based file formats detection.
106  * [Matroska 3D Video (MK3D)](`FileFormat::Matroska3dVideo`)
107  * [Matroska Audio (MKA)](`FileFormat::MatroskaAudio`)
108  * [Matroska Subtitles (MKS)](`FileFormat::MatroskaSubtitles`)
109  * [Matroska Video (MKV)](`FileFormat::MatroskaVideo`)
110  * [WebM](`FileFormat::Webm`)
111- `reader-exe` - Enables [MS-DOS Executable (EXE)](`FileFormat::MsDosExecutable`) based file formats
112  detection.
113  * [Dynamic Link Library (DLL)](`FileFormat::DynamicLinkLibrary`)
114  * [Linear Executable (LE)](`FileFormat::LinearExecutable`)
115  * [New Executable (NE)](`FileFormat::NewExecutable`)
116  * [Portable Executable (PE)](`FileFormat::PortableExecutable`)
117- `reader-id3v2` - Enables [ID3v2 (ID3)](`FileFormat::Id3v2`) based file formats detection.
118  * [Free Lossless Audio Codec (FLAC)](`FileFormat::FreeLosslessAudioCodec`)
119  * [MPEG-1/2 Audio Layer 3 (MP3)](`FileFormat::Mpeg12AudioLayer3`)
120- `reader-mp4` - Enables [MPEG-4 Part 14 (MP4)](`FileFormat::Mpeg4Part14`) based file formats
121  detection.
122  * [MPEG-4 Part 14 Audio (MP4)](`FileFormat::Mpeg4Part14Audio`)
123  * [MPEG-4 Part 14 Subtitles (MP4)](`FileFormat::Mpeg4Part14Subtitles`)
124  * [MPEG-4 Part 14 Video (MP4)](`FileFormat::Mpeg4Part14Video`)
125- `reader-pdf` - Enables [Portable Document Format (PDF)](`FileFormat::PortableDocumentFormat`)
126  based file formats detection.
127  * [Adobe Illustrator Artwork (AI)](`FileFormat::AdobeIllustratorArtwork`)
128- `reader-rm` - Enables [RealMedia (RM)](`FileFormat::Realmedia`) based file formats detection.
129  * [RealAudio (RA)](`FileFormat::Realaudio`)
130  * [RealVideo (RV)](`FileFormat::Realvideo`)
131- `reader-sqlite3` - Enables [SQLite 3](`FileFormat::Sqlite3`) based file formats detection.
132  * [Sketch](`FileFormat::Sketch`)
133- `reader-txt` - Enables [Plain Text (TXT)](`FileFormat::PlainText`) detection when the file format
134  is not recognized by its signature. Please note that this feature only detects files containing
135  ASCII/UTF-8-encoded text.
136- `reader-xml` - Enables [Extensible Markup Language (XML)](`FileFormat::ExtensibleMarkupLanguage`)
137  based file formats detection. Please note that these file formats may be detected without the
138  feature in certain cases.
139  * [AbiWord (ABW)](`FileFormat::Abiword`)
140  * [AbiWord Template (AWT)](`FileFormat::AbiwordTemplate`)
141  * [Additive Manufacturing Format (AMF)](`FileFormat::AdditiveManufacturingFormat`)
142  * [Advanced Stream Redirector (ASX)](`FileFormat::AdvancedStreamRedirector`)
143  * [Atom](`FileFormat::Atom`)
144  * [Collaborative Design Activity (COLLADA)](`FileFormat::CollaborativeDesignActivity`)
145  * [Extensible 3D (X3D)](`FileFormat::Extensible3d`)
146  * [Extensible Stylesheet Language Transformations (XSLT)](`FileFormat::ExtensibleStylesheetLanguageTransformations`)
147  * [FictionBook (FB2)](`FileFormat::Fictionbook`)
148  * [GPS Exchange Format (GPX)](`FileFormat::GpsExchangeFormat`)
149  * [Geography Markup Language (GML)](`FileFormat::GeographyMarkupLanguage`)
150  * [Keyhole Markup Language (KML)](`FileFormat::KeyholeMarkupLanguage`)
151  * [MPEG-DASH MPD (MPD)](`FileFormat::MpegDashMpd`)
152  * [Mathematical Markup Language (MathML)](`FileFormat::MathematicalMarkupLanguage`)
153  * [MusicXML](`FileFormat::Musicxml`)
154  * [Really Simple Syndication (RSS)](`FileFormat::ReallySimpleSyndication`)
155  * [Scalable Vector Graphics (SVG)](`FileFormat::ScalableVectorGraphics`)
156  * [Simple Object Access Protocol (SOAP)](`FileFormat::SimpleObjectAccessProtocol`)
157  * [Tiled Map XML (TMX)](`FileFormat::TiledMapXml`)
158  * [Tiled Tileset XML (TSX)](`FileFormat::TiledTilesetXml`)
159  * [Timed Text Markup Language (TTML)](`FileFormat::TimedTextMarkupLanguage`)
160  * [Training Center XML (TCX)](`FileFormat::TrainingCenterXml`)
161  * [Uniform Office Format Presentation (UOP)](`FileFormat::UniformOfficeFormatPresentation`)
162  * [Uniform Office Format Spreadsheet (UOS)](`FileFormat::UniformOfficeFormatSpreadsheet`)
163  * [Uniform Office Format Text (UOT)](`FileFormat::UniformOfficeFormatText`)
164  * [Universal Subtitle Format (USF)](`FileFormat::UniversalSubtitleFormat`)
165  * [XML Localization Interchange File Format (XLIFF)](`FileFormat::XmlLocalizationInterchangeFileFormat`)
166  * [XML Shareable Playlist Format (XSPF)](`FileFormat::XmlShareablePlaylistFormat`)
167  * [draw.io (DRAWIO)](`FileFormat::DrawIo`)
168- `reader-zip` - Enables [ZIP](`FileFormat::Zip`)-based file formats detection.
169  * [3D Manufacturing Format (3MF)](`FileFormat::ThreeDimensionalManufacturingFormat`)
170  * [Adobe Integrated Runtime (AIR)](`FileFormat::AdobeIntegratedRuntime`)
171  * [Android App Bundle (AAB)](`FileFormat::AndroidAppBundle`)
172  * [Android Package (APK)](`FileFormat::AndroidPackage`)
173  * [Autodesk 123D (123DX)](`FileFormat::Autodesk123d`)
174  * [Circuit Diagram Document (CDDX)](`FileFormat::CircuitDiagramDocument`)
175  * [Design Web Format XPS (DWFX)](`FileFormat::DesignWebFormatXps`)
176  * [Electronic Publication (EPUB)](`FileFormat::ElectronicPublication`)
177  * [Enterprise Application Archive (EAR)](`FileFormat::EnterpriseApplicationArchive`)
178  * [FictionBook ZIP (FBZ)](`FileFormat::FictionbookZip`)
179  * [Figma Design (FIG)](`FileFormat::FigmaDesign`)
180  * [Flash CS5 Project (FLA)](`FileFormat::FlashCs5Project`)
181  * [Fusion 360 (F3D)](`FileFormat::Fusion360`)
182  * [InDesign Markup Language (IDML)](`FileFormat::IndesignMarkupLanguage`)
183  * [Java Archive (JAR)](`FileFormat::JavaArchive`)
184  * [Keyhole Markup Language ZIP (KMZ)](`FileFormat::KeyholeMarkupLanguageZip`)
185  * [Microsoft Visual Studio Extension (VSIX)](`FileFormat::MicrosoftVisualStudioExtension`)
186  * [MusicXML ZIP (MXL)](`FileFormat::MusicxmlZip`)
187  * [Office Open XML Document (DOCX)](`FileFormat::OfficeOpenXmlDocument`)
188  * [Office Open XML Drawing (VSDX)](`FileFormat::OfficeOpenXmlDrawing`)
189  * [Office Open XML Presentation (PPTX)](`FileFormat::OfficeOpenXmlPresentation`)
190  * [Office Open XML Spreadsheet (XLSX)](`FileFormat::OfficeOpenXmlSpreadsheet`)
191  * [OpenDocument Database (ODB)](`FileFormat::OpendocumentDatabase`)
192  * [OpenDocument Formula (ODF)](`FileFormat::OpendocumentFormula`)
193  * [OpenDocument Formula Template (OTF)](`FileFormat::OpendocumentFormulaTemplate`)
194  * [OpenDocument Graphics (ODG)](`FileFormat::OpendocumentGraphics`)
195  * [OpenDocument Graphics Template (OTG)](`FileFormat::OpendocumentGraphicsTemplate`)
196  * [OpenDocument Presentation (ODP)](`FileFormat::OpendocumentPresentation`)
197  * [OpenDocument Presentation Template (OTP)](`FileFormat::OpendocumentPresentationTemplate`)
198  * [OpenDocument Spreadsheet (ODS)](`FileFormat::OpendocumentSpreadsheet`)
199  * [OpenDocument Spreadsheet Template (OTS)](`FileFormat::OpendocumentSpreadsheetTemplate`)
200  * [OpenDocument Text (ODT)](`FileFormat::OpendocumentText`)
201  * [OpenDocument Text Master (ODM)](`FileFormat::OpendocumentTextMaster`)
202  * [OpenDocument Text Master Template (OTM)](`FileFormat::OpendocumentTextMasterTemplate`)
203  * [OpenDocument Text Template (OTT)](`FileFormat::OpendocumentTextTemplate`)
204  * [OpenRaster (ORA)](`FileFormat::Openraster`)
205  * [OpenXPS (OXPS)](`FileFormat::Openxps`)
206  * [Sketch 43](`FileFormat::Sketch43`)
207  * [SpaceClaim Document (SCDOC)](`FileFormat::SpaceclaimDocument`)
208  * [Sun XML Calc (SXC)](`FileFormat::SunXmlCalc`)
209  * [Sun XML Calc Template (STC)](`FileFormat::SunXmlCalcTemplate`)
210  * [Sun XML Draw (SXD)](`FileFormat::SunXmlDraw`)
211  * [Sun XML Draw Template (STD)](`FileFormat::SunXmlDrawTemplate`)
212  * [Sun XML Impress (SXI)](`FileFormat::SunXmlImpress`)
213  * [Sun XML Impress Template (STI)](`FileFormat::SunXmlImpressTemplate`)
214  * [Sun XML Math (SXM)](`FileFormat::SunXmlMath`)
215  * [Sun XML Writer (SXW)](`FileFormat::SunXmlWriter`)
216  * [Sun XML Writer Global (SGW)](`FileFormat::SunXmlWriterGlobal`)
217  * [Sun XML Writer Template (STW)](`FileFormat::SunXmlWriterTemplate`)
218  * [Universal Scene Description ZIP (USDZ)](`FileFormat::UniversalSceneDescriptionZip`)
219  * [Web Application Archive (WAR)](`FileFormat::WebApplicationArchive`)
220  * [Windows App Bundle (APPXBUNDLE)](`FileFormat::WindowsAppBundle`)
221  * [Windows App Package (APPX)](`FileFormat::WindowsAppPackage`)
222  * [XAP](`FileFormat::Xap`)
223  * [XPInstall (XPI)](`FileFormat::Xpinstall`)
224  * [iOS App Store Package (IPA)](`FileFormat::IosAppStorePackage`)
225*/
226
227#![deny(missing_docs)]
228#![forbid(unsafe_code)]
229
230#[macro_use]
231mod macros;
232
233mod formats;
234mod readers;
235mod signatures;
236
237use std::{
238    fmt::{self, Display, Formatter},
239    fs::File,
240    io::{Cursor, Read, Result, Seek},
241    path::Path,
242};
243
244pub use formats::FileFormat;
245
246impl FileFormat {
247    /// Determines the file format from bytes.
248    ///
249    /// # Examples
250    ///
251    /// Detects from the first bytes of a
252    /// [Portable Network Graphics (PNG)](`FileFormat::PortableNetworkGraphics`) file:
253    ///
254    /// ```
255    /// use file_format::FileFormat;
256    ///
257    /// let fmt = FileFormat::from_bytes(b"\x89\x50\x4E\x47\x0D\x0A\x1A\x0A");
258    /// assert_eq!(fmt, FileFormat::PortableNetworkGraphics);
259    ///```
260    ///
261    /// Detects from a zeroed buffer:
262    ///
263    /// ```
264    /// use file_format::FileFormat;
265    ///
266    /// let fmt = FileFormat::from_bytes(&[0; 1000]);
267    /// assert_eq!(fmt, FileFormat::ArbitraryBinaryData);
268    ///```
269    #[inline]
270    pub fn from_bytes<B: AsRef<[u8]>>(bytes: B) -> Self {
271        Self::from(bytes.as_ref())
272    }
273
274    /// Determines the file format from a file.
275    ///
276    /// This method opens the file at the given path and reads its entire contents into memory
277    /// for detection.
278    ///
279    /// # Examples
280    ///
281    /// Basic usage:
282    ///
283    /// ```no_run
284    /// use file_format::FileFormat;
285    ///
286    /// let fmt = FileFormat::from_file("fixtures/video/sample.avi")?;
287    /// assert_eq!(fmt, FileFormat::AudioVideoInterleave);
288    /// # Ok::<(), std::io::Error>(())
289    ///```
290    #[inline]
291    pub fn from_file<P: AsRef<Path>>(path: P) -> Result<Self> {
292        Self::from_reader(File::open(path)?)
293    }
294
295    /// Determines the file format from a reader.
296    ///
297    /// The reader must implement both [`Read`] and [`Seek`] so the detection logic can read
298    /// the initial bytes and then rewind for format-specific deep readers.
299    ///
300    /// # Examples
301    ///
302    /// Basic usage:
303    ///
304    /// ```
305    /// use file_format::FileFormat;
306    ///
307    /// let fmt = FileFormat::from_reader(std::io::empty())?;
308    /// assert_eq!(fmt, FileFormat::Empty);
309    /// # Ok::<(), std::io::Error>(())
310    ///```
311    pub fn from_reader<R: Read + Seek>(mut reader: R) -> Result<Self> {
312        let mut buf = vec![0u8; Self::SIGNATURE_MAX_LEN];
313        let mut nread = 0;
314        while nread < buf.len() {
315            match reader.read(&mut buf[nread..])? {
316                0 => break,
317                n => nread += n,
318            }
319        }
320
321        Ok(if nread == 0 {
322            Self::Empty
323        } else if let Some(fmt) = Self::from_signature(&buf[..nread]) {
324            Self::from_fmt_reader(fmt, &mut reader)
325                .unwrap_or_else(|_| Self::from_generic_reader(&mut reader))
326        } else {
327            Self::from_generic_reader(&mut reader)
328        })
329    }
330}
331
332impl Default for FileFormat {
333    /// Returns the default file format which is
334    /// [Arbitrary Binary Data (BIN)](`FileFormat::ArbitraryBinaryData`).
335    #[inline]
336    fn default() -> Self {
337        Self::ArbitraryBinaryData
338    }
339}
340
341impl Display for FileFormat {
342    #[inline]
343    fn fmt(&self, formatter: &mut Formatter<'_>) -> fmt::Result {
344        write!(formatter, "{}", self.name())
345    }
346}
347
348impl From<&[u8]> for FileFormat {
349    #[inline]
350    fn from(value: &[u8]) -> Self {
351        Self::from_reader(Cursor::new(value)).unwrap_or_default()
352    }
353}
354
355/// The broad category a [`FileFormat`] belongs to.
356///
357/// Every file format is classified into exactly one kind, such as [`Image`](Kind::Image),
358/// [`Audio`](Kind::Audio), [`Document`](Kind::Document), and so on. Use
359/// [`FileFormat::kind`] to retrieve it, or [`FileFormat::from_kind`] to list all formats
360/// in a given category.
361#[derive(Clone, Copy, Debug, Eq, Hash, Ord, PartialEq, PartialOrd)]
362#[non_exhaustive]
363pub enum Kind {
364    /// Files and directories stored in a single, possibly compressed, archive.
365    Archive,
366    /// Musics, sound effects, and spoken audio recordings.
367    Audio,
368    /// Compressed single files or streams.
369    Compressed,
370    /// Organized collections of data.
371    Database,
372    /// Visual information using graphics and spatial relationships.
373    Diagram,
374    /// Floppy disk images, optical disc images and virtual machine disks.
375    Disk,
376    /// Word processing and desktop publishing documents.
377    Document,
378    /// Electronic books.
379    Ebook,
380    /// Machine-executable code, virtual machine code and shared libraries.
381    Executable,
382    /// Typefaces used for displaying text on screen or in print.
383    Font,
384    /// Mathematical formulas.
385    Formula,
386    /// Collections of geospatial features, GPS tracks and other location-related files.
387    Geospatial,
388    /// Animated images, icons, cursors, raster graphics and vector graphics.
389    Image,
390    /// Data that provides information about other data.
391    Metadata,
392    /// 3D models, CAD drawings, and other types of files used for creating or displaying 3D images.
393    Model,
394    /// Data which do not fit in any of the other kinds.
395    Other,
396    /// Collections of files bundled together for software distribution.
397    Package,
398    /// Lists of audio or video files, organized in a specific order for sequential playback.
399    Playlist,
400    /// Slide shows.
401    Presentation,
402    /// Copies of a read-only memory chip of computers, cartridges, or other electronic devices.
403    Rom,
404    /// Data in tabular form.
405    Spreadsheet,
406    /// Subtitles and captions.
407    Subtitle,
408    /// Moving images, possibly with color and coordinated sound.
409    Video,
410}