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