identify-stream

Indentify the contents of a Node stream based on the presence of a file signature.

Usage no npm install needed!

<script type="module">
  import identifyStream from 'https://cdn.skypack.dev/identify-stream';
</script>

README

identify-stream

Identify the contents of a Node stream based on the presence of a file signature (magic number). Can be extended to check for additional file formats.

Build Status Coverage Status

Install

$ npm install --save identify-stream

Basic Usage

const identifyStream = new IdentifyStream();
const inputStream = fs.createReadStream('./input.png');
const outputStream = fs.createWriteStream('./output.png');

inputStream.pipe(identifyStream).pipe(outputStream);

identifyStream.on('complete', (result) => {
  console.log(result); // {name: "PNG Image", extension: "png", mime: "image/png"}
});

Detecting Subtypes

Some file formats have two or more different variants, each with their own distinct file signature. Where this is the case the result object will feature an additional subtype property as seen below:

const identifyStream = new IdentifyStream();
const inputStream = fs.createReadStream('./input.gif');
const outputStream = fs.createWriteStream('./output.gig');

inputStream.pipe(identifyStream).pipe(outputStream);

identifyStream.on('complete', (result) => {
  console.log(result); // {name: "GIF Image", extension: "gif", mime: "image/gif", subtype: "87a"}
});

Detecting Custom Formats

Instances of IdentifyStream may be extended to detect additional file formats. See Defining Custom Formats for more information.

const identifyStream = new IdentifyStream({
  formats: {
    extension: 'pseudo format',
    extension: 'pseudo',
    mime: 'application/x-custom',
    signature: [{
      value: '7fa92c',
      offset: 0
    }];
  }
});
const inputStream = fs.createReadStream('./input.pseudo');
const outputStream = fs.createWriteStream('./output.pseudo');

inputStream.pipe(identifyStream).pipe(outputStream);

identifyStream.on('complete', (result) => {
  console.log(result); // {name: "pseudo format", extension: "pseudo", mime: "application/x-custom"}
});

API

new IdentityStream([options])

  • options
    • formats {Format | <Format[]} An optional list of custom file formats to detect (See below).

    • highWaterMark {Number} The node streams highWaterMark setting. Default: 16384

    Defining Custom Formats

    Instances of IdentifyStream may be configured to detect file formats beyond those already supported. To do so, use the formats option to provide one or more Format objects. See /data/formats.json for examples.

    Format

    Each Format object should have either a signature or a subtypes property.

    Property Type Description
    extension String The file formats's extension
    mime String The file formats's MIME type.
    signature Signature ⎮ Signature[] One or more Signature objects. Identity-Stream will only match with this format if all signatures are present in the stream.
    subtypes Subtype ⎮ Subtype[] One or more Subtype objects. Identity-Stream will match with this format if any subtype's signature matches.

    SubType

    Property Type Description
    name String The name of this subtype
    signature Signature ⎮ Signature[] One or more Signature objects. Identity-Stream will only match with this subtype if all signatures are present in the stream.

    Signature

    Property Type Description
    value String The signature to check for (in hex format).
    offset Number The offset of the signatue in bytes.

    Events

    complete

    The complete event is emitted when the stream has succesfully identified the stream file format, or ruled out all known file formats. Callback functions attached to this event receive an object describing streamed file, or null if the format is not recognized.

    error

    The error event is emitted when the stream encounters an unexpected situation, for example if it is connected to an object stream.

    Supported File Types

    Extension MIME type
    7z application/x-7z-compressed
    avi video/avi
    bmp image/bmp
    bz2 application/bzip2
    exe application/octet-stream
    flac audio/flac
    gif image/gif
    gz application/gzip
    ico image/ico
    jpg image/jpeg
    jpf image/jpx
    m4a audio/m4a
    mov video/quicktime
    mp3 audio/mpeg
    mp4 video/mp4
    ogg audio/ogg
    pdf application/pdf
    png image/png
    psd image/psd
    rtf application/rtf
    tiff image/tiff
    wav audio/wav
    webm video/webm
    webp image/webp
    xz application/x-xz
    zip application/zip

    License

    ISC