Node-Metadata

An advanced Node.js interface to the exiftool. 🚀

“An amazing level of senseless perfectionism, which is simply impossible not to respect.”

Exiftool is an amazing tool written by Phil Harvey in Perl which can read and write metadata to a number of file formats. This library supports streams. So, you don't have to handle anything from your end. It also cache network files to save your bandwidth.

Requirements
API
Advanced
Experimental Features
Test
- Jest
Tools
Known Issues
Sponsor
License

Install

npm install @enviro/metadata

Requirements

Exiftool need perl to be installed on your system, Download Perl.
Node.js version >= 16.x
ExifTool is no longer included with this package, Download ExifTool. Read more about seamless ExifTool integration using path option in documentation.

Import & Configure

import Metadata from "@enviro/metadata";

// OPTIONAL
// only required if you are using user-defined tags
async function config() {
    await Metadata.configurator({
        default: true,
        no_cache_cleanup: true,
        tags: [
            {
                name: "CUSTOM_TAG",
                type: "string",
                exifPropGroup: "Exif",
                exifPropSubGroup: "Main",
            },
            {
                name: "CUSTOM_TAG",
                type: "string",
                exifPropGroup: "PDF",
                exifPropSubGroup: "Info",
            },
        ],
    });
}

Options

| Name | Type | Description | | --- | --- | --- | | default | boolean | [Advanced] Default undefined The default configuration use hex keys in file. If you want to use key name in file, set this option explicitly false. | | keyCodeEvaluator | number | [Advanced] The value must be greater than 53248. This is the default key for the first user-defined tag. | | no_cache_cleanup | boolean | This will stop auto cache cleaner on node server startup. | | tags | [ExifCustomTag] | Configure Exiftool to add or remove new metadata tags to the file. |
- ExifCustomTag
 
 | Name | Type | Description | | --- | --- | --- | | name | string | The name of the custom tag. | | type | "string" | Type of the custom tag's value. You can pass custom valid type in here which is supported by exif tag group. | | exifPropGroup | "Exif"|"PDF"| string | The custom tag's belongs to this group. Custom group can be passed as an argument. Read more at Family 0 (Information Type) | | exifPropSubGroup | "Main"|"Info"| string | The custom tag's belongs to this specific sub group. Custom sub-group can be passed as an argument. Read more at Family 1 (Specific Location) |

API

Extract Metadata

Local File

async function read() {
    try {
        const metadata = await Metadata.get("test.pdf", {
            // path not required, since ExifTool is accessible from terminal using exiftool.
            // path: "exiftool",
            tags: [
                {
                    name: "FileName",
                    exclude: true,
                },
            ],
        });
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

Output

[
    {
        FileSize: "89 kB",
        FileModifyDate: "2022:11:11 17:08:58+05:00",
        FileAccessDate: "2022:11:11 17:08:58+05:00",
        FileInodeChangeDate: "2022:11:11 17:08:58+05:00",
        FilePermissions: "-rwxrwxrwx",
        FileType: "PDF",
        FileTypeExtension: "pdf",
        MIMEType: "application/pdf",
        PDFVersion: 1.3,
        Linearized: "No",
        Encryption: "Standard V1.2 (40-bit)",
        UserAccess:
            "Print, Copy, Annotate, Fill forms, Extract, Assemble, Print high-res",
        CreateDate: "2001:10:26 13:39:34",
        Producer: "Acrobat Distiller 4.05 for Windows",
        ModifyDate: "2001:10:26 13:40:41-04:00",
        Title: "PDF Bookmark Sample",
        Author: "Accelio Corporation",
        PageCount: 4,
    },
];

FileName excluded from the result.

File Stream

import { createReadStream } from "node:fs";

async function streamFile() {
    try {
        const rs = createReadStream("sample.pdf");
        const metadata = await Metadata.get(rs, {
            path: "path/to/ExifTool",
        });
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

Network Stream

async function streamURL() {
    try {
        const metadata = await Metadata.get(
            "https://www.w3.org/WAI/ER/tests/xhtml/testfiles/resources/pdf/dummy.pdf",
            {
                no_cache: true,
            }
        );
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

Options

| Name | Type | Description | | --- | --- | --- | | fileName | string | Read: Cache file name. | | no_cache | boolean | This option doesn't work on local file path passed as a parameter. no_cache: true default for stream, read more about Stream caching. no_cache: false default for network file, read more Network stream. | | tags | [ExifReadOPTag] | Filter the output metadata tags either excluded them or only include them. | | all | boolean | Default false If true, all the metadata tags will be returned. This will override the tags option. NOTE: This option can cause significant performance issues. Use it only if you need all the metadata tags. | | batch | BatchReadOptions | Options for batch processing. |

ExifReadOPTag

| Name | Type | Description | | --- | --- | --- | | name | string | Name of the metadata tag. | | exclude | boolean | exclude: true exclude this tag from the result. exclude: false make this tag exclusive. | | custom | string | [Advanced] Custom Exiftool reading command can be directly passed to custom. Read more about exiftool commands. |
BatchReadOptions

| Name | Type | Description | | --- | --- | --- | | no_network_cache | boolean|[string] | Default false. If true, the network files will not be cached. If specified list of URLs provided, than that URLs will not be cached. | | no_stream_cache | [string] | Default null. If file name is not valid for stream perspective, then that specific stream will not be cached. [] or null means all streams will be discarded after reading metadata. |

Add/Edit Metadata

Local File

async function write() {
    try {
        const metadata = await Metadata.set("sample.pdf", {
            tags: [
                {
                    name: "CUSTOM_TAG",
                    value: "custom value",
                },
            ],
        });
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

File Stream

async function streamFile() {
    try {
        const rs = createReadStream("sample.pdf");
        const metadata = await Metadata.set(rs, {
            path: "path/to/ExifTool",
            tags: [
                {
                    name: "CUSTOM_TAG",
                    value: null,
                },
            ],
        });
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

An empty tag will delete the tag from the file.

Network Stream

async function streamURL() {
    try {
        // NOTE: This pdf has a size of 26 MB
        const metadata = await Metadata.set(
            "https://research.nhm.org/pdfs/10840/10840.pdf",
            {
                path: "path/to/ExifTool",
                new: true,
                prev: true,
                tags: [
                    {
                        name: "CUSTOM_TAG",
                        value: "NEW VALUE",
                    },
                ],
            }
        );
        console.log(metadata);
    } catch (e) {
        console.error(e);
    }
}

OUTPUT

{
    message: 'File updated successfully!',
    // Path to the file which metadata was edited
    file: '../../dir/to/the/sample.pdf',
    // OR
    // This type of path will be generated for streams
    file: '../../path/to/dir/.tmp/0b00f9b2-cc7d-48b6-8fad-d

Metadata

Install / Use

README

Node-Metadata

Table of Contents

Install

Requirements

Import & Configure

Options

ExifCustomTag

API

Extract Metadata

Local File

Output

File Stream

Network Stream

Options

ExifReadOPTag

BatchReadOptions

Add/Edit Metadata

Local File

File Stream

Network Stream

OUTPUT