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.

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