is a Ruby library for prying open video, image, document, and audio files. It includes a number of parser modules that try to recover metadata useful for post-processing and layout while reading the absolute minimum amount of data possible.
format_parser is inspired by imagesize, fastimage
and dimensions, borrowing from them where appropriate.
- TIFF
- CR2
- PSD
- PNG
- MP3
- JPEG
- GIF
- DPX
- AIFF
- WAV
- FLAC
- FDX
- MOV
- MP4
- M4A
- ZIP
- DOCX, PPTX, XLSX
- OGG
- MPEG, MPG
- M3U
...with more on the way!
Pass an IO object that responds to read, seek and size to FormatParser.parse and the first confirmed match will be returned.
match = FormatParser.parse(File.open("myimage.jpg", "rb"))
match.nature #=> :image
match.format #=> :jpg
match.display_width_px #=> 320
match.display_height_px #=> 240
match.orientation #=> :top_leftYou can also use parse_http passing a URL or parse_file_at passing a path:
match = FormatParser.parse_http('https://upload.wikimedia.org/wikipedia/commons/b/b4/Mardin_1350660_1350692_33_images.jpg')
match.nature #=> :image
match.format #=> :jpgIf you would rather receive all potential results from the gem, call the gem as follows:
array_of_results = FormatParser.parse(File.open("myimage.jpg", "rb"), results: :all)You can also optimize the metadata extraction by providing hints to the gem:
FormatParser.parse(File.open("myimage", "rb"), natures: [:video, :image], formats: [:jpg, :png, :mp4], results: :all)Return values of all parsers have built-in JSON serialization
img_info = FormatParser.parse(File.open("myimage.jpg", "rb"))
JSON.pretty_generate(img_info) #=> ...To convert the result to a Hash or a structure suitable for JSON serialization
img_info = FormatParser.parse(File.open("myimage.jpg", "rb"))
img_info.as_json
# it's also possible to convert all keys to string
img_info.as_json(stringify_keys: true)See the section on writing parsers in CONTRIBUTING.md
We need to recover metadata from various file types, and we need to do so satisfying the following constraints:
- The data in those files can be malicious and/or incomplete, so we need to be failsafe
- The data will be fetched from a remote location (S3), so we want to obtain it with as few HTTP requests as possible
- ...and with the amount of data fetched being small - the number of HTTP requests being of greater concern
- The data can be recognized ambiguously and match more than one format definition (like TIFF sections of camera RAW)
- The information necessary is a small subset of the overall metadata available in the file.
- The number of supported formats is only ever going to increase, not decrease
- The library is likely to be used in multiple consumer applications
- The library is likely to be used in multithreading environments
Therefore we adapt the following approaches:
- Modular parsers per file format, with some degree of code sharing between them (but not too much). Adding new formats should be low-friction, and testing these format parsers should be possible in isolation
- Modular and configurable IO stack that supports limiting reads/loops from the source entity.
The IO stack is isolated from the parsers, meaning parsers do not need to care about things
like fetches using
Range:headers, GZIP compression and the like - A caching system that allows us to ideally fetch once, and only once, and as little as possible - but still accomodate formats that have the important information at the end of the file or might need information from the middle of the file
- Minimal dependencies, and if dependencies are to be used they should be very stable and low-level
- Where possible, use small subsets of full-feature format parsers since we only care about a small subset of the data.
- When a choice arises between using a dependency or writing a small parser, write the small parser since less code is easier to verify and test, and we likely don't care about all the metadata anyway
- Avoid using C libraries which are likely to contain buffer overflows/underflows - we stay memory safe
We are incredibly grateful to Remco van't Veer for exifr and to Krists Ozols for id3tag that we are using for crucial tasks.
Unless specified otherwise in this section the fixture files are MIT licensed and from the FastImage and Dimensions projects.
divergent_pixel_dimensions_exif.jpgis used with permission from LiveKom GmbHextended_reads.jpghas kindly been made available by Raphaelle Pellerin for use exclusively with format_parsertoo_many_APP1_markers_surrogate.jpgwas created by the project maintainers
orient_6.jpgis used with permission from Renaud Chaput
- fixture.aiff was created by one of the project maintainers and is MIT licensed
- c_11k16bitpcm.wav and c_8kmp316.wav are from Wikipedia WAV, retrieved January 7, 2018
- c_39064__alienbomb__atmo-truck.wav is from freesound and is CC0 licensed
- c_M1F1-Alaw-AFsp.wav and d_6_Channel_ID.wav are from a McGill Engineering site
- Cassy.mp3 has been produced by WeTransfer and may be used with the library for the purposes of testing
- fixture.fdx was created by one of the project maintainers and is MIT licensed
- DPX files were created by one of the project maintainers and may be used with the library for the purposes of testing
- bmff.mp4 is borrowed from the bmff project
- Test_Circular MOV files were created by one of the project maintainers and are MIT licensed
- CR2 examples are downloaded from http://www.rawsamples.ch/ and are Creative Common Licensed.
- atc_fixture_vbr.flac is a converted version of the MP3 with the same name
- c_11k16btipcm.flac is a converted version of the WAV with the same name
hi.ogg,vorbis.ogg,with_confusing_magic_string.ogg,with_garbage_at_the_end.ogghave been generated by the project contributors
- fixture.m4a was created by one of the project maintainers and is MIT licensed
simulator_screenie.pngprovided by Rens Verhoeven
Shinbutsureijoushuincho.tiffis obtained from Wikimedia Commons and is Creative Commons licensedIMG_9266_*.tifand all it's variations were created by the project maintainers
- ARW example is downloaded from http://www.rawsamples.ch/ and is Creative Common Licensed.
- The .zip fixture files have been created by the project maintainers
- The .docx files were generated by the project maintainers
- The files (video 1 to 4) were downloaded from https://standaloneinstaller.com/blog/big-list-of-sample-videos-for-testers-124.html.
- Video 5 was downloaded from https://archive.org/details/ligouHDR-HC1_sample1.
- Downloaded from Unspash (and thus freely avaliable) - https://unsplash.com/license and have then been manipulated using the https://github.com/recurser/exif-orientation-examples script.
- The M3U fixture files were created by one of the project maintainers
- The
keynote_recognized_as_jpeg.keyfile was created by the project maintainers
Copyright (c) 2020 WeTransfer.
format_parser is distributed under the conditions of the Hippocratic License
- See LICENSE.txt for further details.