README.md
1<h1 align="center">
2 mimetype
3</h1>
4
5<h4 align="center">
6 A package for detecting MIME types and extensions based on magic numbers
7</h4>
8<h6 align="center">
9 Goroutine safe, extensible, no C bindings
10</h6>
11
12<p align="center">
13 <a href="https://travis-ci.org/gabriel-vasile/mimetype">
14 <img alt="Build Status" src="https://travis-ci.org/gabriel-vasile/mimetype.svg?branch=master">
15 </a>
16 <a href="https://pkg.go.dev/github.com/gabriel-vasile/mimetype">
17 <img src="https://pkg.go.dev/badge/github.com/gabriel-vasile/mimetype.svg" alt="Go Reference">
18 </a>
19 <a href="https://goreportcard.com/report/github.com/gabriel-vasile/mimetype">
20 <img alt="Go report card" src="https://goreportcard.com/badge/github.com/gabriel-vasile/mimetype">
21 </a>
22 <a href="https://coveralls.io/github/gabriel-vasile/mimetype?branch=master">
23 <img alt="Go report card" src="https://coveralls.io/repos/github/gabriel-vasile/mimetype/badge.svg?branch=master">
24 </a>
25 <a href="LICENSE">
26 <img alt="License" src="https://img.shields.io/badge/License-MIT-green.svg">
27 </a>
28</p>
29
30## Features
31- fast and precise MIME type and file extension detection
32- long list of [supported MIME types](supported_mimes.md)
33- posibility to [extend](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#example-package-Extend) with other file formats
34- common file formats are prioritized
35- safe for concurrent usage
36
37## Install
38```bash
39go get github.com/gabriel-vasile/mimetype
40```
41
42## Usage
43```go
44mtype := mimetype.Detect([]byte)
45// OR
46mtype, err := mimetype.DetectReader(io.Reader)
47// OR
48mtype, err := mimetype.DetectFile("/path/to/file")
49fmt.Println(mtype.String(), mtype.Extension())
50```
51See the [runnable Go Playground examples](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#pkg-overview).
52
53## Usage'
54Only use libraries like **mimetype** as a last resort. Content type detection
55using magic numbers is slow, inaccurate, and non-standard. Most of the times
56protocols have methods for specifying such metadata; e.g., `Content-Type` header
57in HTTP and SMTP.
58
59## Structure
60**mimetype** uses a hierarchical structure to keep the MIME type detection logic.
61This reduces the number of calls needed for detecting the file type. The reason
62behind this choice is that there are file formats used as containers for other
63file formats. For example, Microsoft Office files are just zip archives,
64containing specific metadata files. Once a file has been identified as a
65zip, there is no need to check if it is a text file, but it is worth checking if
66it is an Microsoft Office file.
67
68To prevent loading entire files into memory, when detecting from a
69[reader](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#DetectReader)
70or from a [file](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#DetectFile)
71**mimetype** limits itself to reading only the header of the input.
72<div align="center">
73 <img alt="structure" src="https://github.com/gabriel-vasile/mimetype/blob/420a05228c6a6efbb6e6f080168a25663414ff36/mimetype.gif?raw=true" width="88%">
74</div>
75
76## Performance
77Thanks to the hierarchical structure, searching for common formats first,
78and limiting itself to file headers, **mimetype** matches the performance of
79stdlib `http.DetectContentType` while outperforming the alternative package.
80
81```bash
82 mimetype http.DetectContentType filetype
83BenchmarkMatchTar-24 250 ns/op 400 ns/op 3778 ns/op
84BenchmarkMatchZip-24 524 ns/op 351 ns/op 4884 ns/op
85BenchmarkMatchJpeg-24 103 ns/op 228 ns/op 839 ns/op
86BenchmarkMatchGif-24 139 ns/op 202 ns/op 751 ns/op
87BenchmarkMatchPng-24 165 ns/op 221 ns/op 1176 ns/op
88```
89
90## Contributing
91See [CONTRIBUTING.md](CONTRIBUTING.md).
92
