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://pkg.go.dev/github.com/gabriel-vasile/mimetype">
14 <img alt="Go Reference" src="https://pkg.go.dev/badge/github.com/gabriel-vasile/mimetype.svg">
15 </a>
16 <a href="https://goreportcard.com/report/github.com/gabriel-vasile/mimetype">
17 <img alt="Go report card" src="https://goreportcard.com/badge/github.com/gabriel-vasile/mimetype">
18 </a>
19 <a href="https://codecov.io/gh/gabriel-vasile/mimetype">
20 <img alt="Code coverage" src="https://codecov.io/gh/gabriel-vasile/mimetype/branch/master/graph/badge.svg?token=qcfJF1kkl2"/>
21 </a>
22 <a href="LICENSE">
23 <img alt="License" src="https://img.shields.io/badge/License-MIT-green.svg">
24 </a>
25</p>
26
27## Features
28- fast and precise MIME type and file extension detection
29- long list of [supported MIME types](supported_mimes.md)
30- possibility to [extend](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#example-package-Extend) with other file formats
31- common file formats are prioritized
32- [text vs. binary files differentiation](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#example-package-TextVsBinary)
33- safe for concurrent usage
34
35## Install
36```bash
37go get github.com/gabriel-vasile/mimetype
38```
39
40## Usage
41```go
42mtype := mimetype.Detect([]byte)
43// OR
44mtype, err := mimetype.DetectReader(io.Reader)
45// OR
46mtype, err := mimetype.DetectFile("/path/to/file")
47fmt.Println(mtype.String(), mtype.Extension())
48```
49See the [runnable Go Playground examples](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#pkg-overview).
50
51## Usage'
52Only use libraries like **mimetype** as a last resort. Content type detection
53using magic numbers is slow, inaccurate, and non-standard. Most of the times
54protocols have methods for specifying such metadata; e.g., `Content-Type` header
55in HTTP and SMTP.
56
57## FAQ
58Q: My file is in the list of [supported MIME types](supported_mimes.md) but
59it is not correctly detected. What should I do?
60
61A: Some file formats (often Microsoft Office documents) keep their signatures
62towards the end of the file. Try increasing the number of bytes used for detection
63with:
64```go
65mimetype.SetLimit(1024*1024) // Set limit to 1MB.
66// or
67mimetype.SetLimit(0) // No limit, whole file content used.
68mimetype.DetectFile("file.doc")
69```
70If increasing the limit does not help, please
71[open an issue](https://github.com/gabriel-vasile/mimetype/issues/new?assignees=&labels=&template=mismatched-mime-type-detected.md&title=).
72
73## Structure
74**mimetype** uses a hierarchical structure to keep the MIME type detection logic.
75This reduces the number of calls needed for detecting the file type. The reason
76behind this choice is that there are file formats used as containers for other
77file formats. For example, Microsoft Office files are just zip archives,
78containing specific metadata files. Once a file has been identified as a
79zip, there is no need to check if it is a text file, but it is worth checking if
80it is an Microsoft Office file.
81
82To prevent loading entire files into memory, when detecting from a
83[reader](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#DetectReader)
84or from a [file](https://pkg.go.dev/github.com/gabriel-vasile/mimetype#DetectFile)
85**mimetype** limits itself to reading only the header of the input.
86<div align="center">
87 <img alt="structure" src="https://github.com/gabriel-vasile/mimetype/blob/420a05228c6a6efbb6e6f080168a25663414ff36/mimetype.gif?raw=true" width="88%">
88</div>
89
90## Performance
91Thanks to the hierarchical structure, searching for common formats first,
92and limiting itself to file headers, **mimetype** matches the performance of
93stdlib `http.DetectContentType` while outperforming the alternative package.
94
95```bash
96 mimetype http.DetectContentType filetype
97BenchmarkMatchTar-24 250 ns/op 400 ns/op 3778 ns/op
98BenchmarkMatchZip-24 524 ns/op 351 ns/op 4884 ns/op
99BenchmarkMatchJpeg-24 103 ns/op 228 ns/op 839 ns/op
100BenchmarkMatchGif-24 139 ns/op 202 ns/op 751 ns/op
101BenchmarkMatchPng-24 165 ns/op 221 ns/op 1176 ns/op
102```
103
104## Contributing
105See [CONTRIBUTING.md](CONTRIBUTING.md).
View as plain text