{"_id":"@aidin36/xmp","_rev":"4-5062d9787e41ce027b1543b7e54b44aa","name":"@aidin36/xmp","dist-tags":{"latest":"0.2.2"},"versions":{"0.1.0":{"name":"@aidin36/xmp","version":"0.1.0","keywords":["iptc","xmp","jpeg","heic","metadata"],"author":{"name":"Aidin Gharibnavaz"},"license":"LGPL-3.0-or-later","_id":"@aidin36/xmp@0.1.0","maintainers":[{"name":"aidin36","email":"aidin@aidinhut.com"}],"homepage":"https://github.com/aidin36/xmp#readme","bugs":{"url":"https://github.com/aidin36/xmp/issues"},"dist":{"shasum":"3ca79f761887e8d301a80c0783c7e97404c5ae9e","tarball":"https://registry.npmjs.org/@aidin36/xmp/-/xmp-0.1.0.tgz","fileCount":11,"integrity":"sha512-YvFQTTN3Hp5m1FZ1K72AuAxJPy0Q3FZ5A1SvaahwCJOwi0FgnR40jeXvl0qmklUsHSLkr2CUXV+cUkLRIyh+cA==","signatures":[{"sig":"MEQCIByNrg8pp6xlb9jofE+YJvBVEfNQl/miHfYGg7Wb3QjvAiADuztd0wLYR9x1ZNx7RPeep4LskMyWbQzPAqqRRfnuvQ==","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":41355},"main":"index.js","types":"index.d.ts","volta":{"node":"22.12.0"},"gitHead":"feb328e5314179aa4765ba46f40c7613c1085863","scripts":{"tsc":"tsc","lint":"eslint --quiet './src/**/*.ts*'","test":"jest","pretty":"prettier './src/**/*.ts*' --write --config .prettierrc","coverage":"jest --coverage","tsc:watch":"tsc --watch"},"_npmUser":{"name":"aidin36","email":"aidin@aidinhut.com"},"repository":{"url":"git+https://github.com/aidin36/xmp.git","type":"git"},"_npmVersion":"10.9.0","description":"Read and write XMP metadata from/to various media formats","directories":{},"_nodeVersion":"22.12.0","dependencies":{"@xmldom/xmldom":"0.9.6","@aidin36/xmp2js":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"29.7.0","eslint":"8.57.1","ts-jest":"29.2.5","prettier":"3.4.2","typescript":"5.7.2","@jest/globals":"29.7.0","eslint-plugin-tsdoc":"0.4.0","eslint-config-airbnb":"19.0.4","eslint-config-prettier":"9.1.0","eslint-plugin-prettier":"5.2.1","@typescript-eslint/parser":"8.19.0","@typescript-eslint/eslint-plugin":"8.19.0"},"_npmOperationalInternal":{"tmp":"tmp/xmp_0.1.0_1742973970773_0.4512530559688692","host":"s3://npm-registry-packages-npm-production"}},"0.2.0":{"name":"@aidin36/xmp","version":"0.2.0","keywords":["iptc","xmp","jpeg","heic","metadata"],"author":{"name":"Aidin Gharibnavaz"},"license":"LGPL-3.0-or-later","_id":"@aidin36/xmp@0.2.0","maintainers":[{"name":"aidin36","email":"aidin@aidinhut.com"}],"homepage":"https://github.com/aidin36/xmp#readme","bugs":{"url":"https://github.com/aidin36/xmp/issues"},"dist":{"shasum":"17b56446caeed29e8b0f4a2db3a4a88c54ae3f71","tarball":"https://registry.npmjs.org/@aidin36/xmp/-/xmp-0.2.0.tgz","fileCount":13,"integrity":"sha512-Q2uCWlYTAX+qN7w+phv/wt0tj4vniK4puKAwp51faSSQgNxNbhommlkE7+RpnlQ4lnnEsQ1WjBl9+bK7zasOlQ==","signatures":[{"sig":"MEUCIQCu2WsDg8PRp4LZyiSWK31jouwbP8tUA0ExwQeDHOVy+gIgFaDmzzuNYqEBPfBD8zynCtduwucQ84BlDSEwK2iKCVY=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":68999},"main":"index.js","types":"index.d.ts","volta":{"node":"22.17.0"},"gitHead":"664199c6e9e51ccb73be3bfbf4736a823418aa87","scripts":{"tsc":"tsc","lint":"eslint --quiet './src/**/*.ts*'","test":"jest","pretty":"prettier './src/**/*.ts*' --write --config .prettierrc","coverage":"jest --coverage","tsc:watch":"tsc --watch"},"_npmUser":{"name":"aidin36","email":"aidin@aidinhut.com"},"repository":{"url":"git+https://github.com/aidin36/xmp.git","type":"git"},"_npmVersion":"10.9.2","description":"Read and write XMP metadata from/to various media formats","directories":{},"_nodeVersion":"22.17.0","dependencies":{"@xmldom/xmldom":"0.9.8","@aidin36/xmp2js":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"30.0.4","eslint":"8.57.1","ts-jest":"29.4.0","prettier":"3.6.2","typescript":"5.8.3","@jest/globals":"30.0.4","eslint-plugin-tsdoc":"0.4.0","eslint-config-airbnb":"19.0.4","eslint-config-prettier":"10.1.5","eslint-plugin-prettier":"5.5.1","@typescript-eslint/parser":"8.36.0","@typescript-eslint/eslint-plugin":"8.36.0"},"_npmOperationalInternal":{"tmp":"tmp/xmp_0.2.0_1752210009421_0.39958969534617594","host":"s3://npm-registry-packages-npm-production"}},"0.2.1":{"name":"@aidin36/xmp","version":"0.2.1","keywords":["iptc","xmp","jpeg","heic","metadata"],"author":{"name":"Aidin Gharibnavaz"},"license":"LGPL-3.0-or-later","_id":"@aidin36/xmp@0.2.1","maintainers":[{"name":"aidin36","email":"aidin@aidinhut.com"}],"homepage":"https://github.com/aidin36/xmp#readme","bugs":{"url":"https://github.com/aidin36/xmp/issues"},"dist":{"shasum":"c053b268f3aadb62bc09d75d36697d288e341329","tarball":"https://registry.npmjs.org/@aidin36/xmp/-/xmp-0.2.1.tgz","fileCount":13,"integrity":"sha512-RsGWU5g8l/87c6D0dtJPExT2fkP4lneSZ12935yVm1Rk7B0NfpaqwWAMVR328T/KKLui0Bg842473VyWXdbjbA==","signatures":[{"sig":"MEUCIQCrAgi5M9FBodxjLHQ+2MBQ6YrqxcBW0+2VvB28SAmZkQIgDENhQ6tMw9gdktUzh8WANxOnlATFytjZo/3Z84ZmxW4=","keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U"}],"unpackedSize":76395},"main":"index.js","types":"index.d.ts","volta":{"node":"22.17.0"},"gitHead":"d33b7c71ea68211d82dcdcbf1be83ba8dee9cf91","scripts":{"tsc":"tsc","lint":"eslint --quiet './src/**/*.ts*'","test":"jest","pretty":"prettier './src/**/*.ts*' --write --config .prettierrc","coverage":"jest --coverage","tsc:watch":"tsc --watch","ci:coverage":"jest --ci --coverage --coverageDirectory './coverage'"},"_npmUser":{"name":"aidin36","email":"aidin@aidinhut.com"},"repository":{"url":"git+https://github.com/aidin36/xmp.git","type":"git"},"_npmVersion":"10.9.2","description":"Read and write XMP metadata from/to various media formats","directories":{},"_nodeVersion":"22.17.0","dependencies":{"@xmldom/xmldom":"0.9.8","@aidin36/xmp2js":"^1.0.0"},"_hasShrinkwrap":false,"devDependencies":{"jest":"30.0.4","eslint":"8.57.1","ts-jest":"29.4.0","prettier":"3.6.2","typescript":"5.8.3","@jest/globals":"30.0.4","eslint-plugin-tsdoc":"0.4.0","eslint-config-airbnb":"19.0.4","eslint-config-prettier":"10.1.5","eslint-plugin-prettier":"5.5.1","@typescript-eslint/parser":"8.36.0","@typescript-eslint/eslint-plugin":"8.36.0"},"_npmOperationalInternal":{"tmp":"tmp/xmp_0.2.1_1752281650083_0.4874981433564278","host":"s3://npm-registry-packages-npm-production"}},"0.2.2":{"name":"@aidin36/xmp","version":"0.2.2","description":"Read and write XMP metadata from/to various media formats","main":"index.js","types":"index.d.ts","scripts":{"tsc":"tsc","tsc:watch":"tsc --watch","pretty":"prettier './src/**/*.ts*' --write --config .prettierrc","lint":"eslint --quiet './src/**/*.ts*'","test":"jest","coverage":"jest --coverage","ci:coverage":"jest --ci --coverage --coverageDirectory './coverage'"},"repository":{"type":"git","url":"git+https://github.com/aidin36/xmp.git"},"keywords":["iptc","xmp","jpeg","heic","metadata"],"author":{"name":"Aidin Gharibnavaz"},"license":"LGPL-3.0-or-later","bugs":{"url":"https://github.com/aidin36/xmp/issues"},"homepage":"https://github.com/aidin36/xmp#readme","volta":{"node":"22.17.0"},"devDependencies":{"@jest/globals":"30.0.4","@typescript-eslint/eslint-plugin":"8.36.0","@typescript-eslint/parser":"8.36.0","eslint":"8.57.1","eslint-config-airbnb":"19.0.4","eslint-config-prettier":"10.1.5","eslint-plugin-prettier":"5.5.1","eslint-plugin-tsdoc":"0.4.0","jest":"30.0.4","prettier":"3.6.2","ts-jest":"29.4.0","typescript":"5.8.3"},"dependencies":{"@aidin36/xmp2js":"^1.0.0","@xmldom/xmldom":"0.9.8"},"_id":"@aidin36/xmp@0.2.2","gitHead":"01bb4f4885dfb1a5525036238e47267319635a5b","_nodeVersion":"22.17.0","_npmVersion":"10.9.2","dist":{"integrity":"sha512-9bFofmwJD6I8BzgEqexO8ZnpS5OhB9qMKhJZyKyFRmyzYZPhdPkT6Dtbc4AShVC1Y0CDhS+fwLyu20+7f5SUBw==","shasum":"dbd17b96247d80907d5fc7a4e86d9b4b954ea41f","tarball":"https://registry.npmjs.org/@aidin36/xmp/-/xmp-0.2.2.tgz","fileCount":13,"unpackedSize":76626,"signatures":[{"keyid":"SHA256:DhQ8wR5APBvFHLF/+Tc+AYvPOdTpcIDqOhxsBHRwC7U","sig":"MEYCIQCIokjF+M5DNC0rWFwzmmsRJ6N9an9XNR5B/+qtk7KuBwIhAJKpAO5zLthvD2n6eVbuAhjuwZpl3Cx8KAoJ41oI3VZ3"}]},"_npmUser":{"name":"aidin36","email":"aidin@aidinhut.com"},"directories":{},"maintainers":[{"name":"aidin36","email":"aidin@aidinhut.com"}],"_npmOperationalInternal":{"host":"s3://npm-registry-packages-npm-production","tmp":"tmp/xmp_0.2.2_1753988360205_0.9637598319935239"},"_hasShrinkwrap":false}},"time":{"created":"2025-03-26T07:26:10.705Z","modified":"2025-07-31T18:59:20.577Z","0.1.0":"2025-03-26T07:26:10.950Z","0.2.0":"2025-07-11T05:00:09.708Z","0.2.1":"2025-07-12T00:54:10.289Z","0.2.2":"2025-07-31T18:59:20.388Z"},"bugs":{"url":"https://github.com/aidin36/xmp/issues"},"author":{"name":"Aidin Gharibnavaz"},"license":"LGPL-3.0-or-later","homepage":"https://github.com/aidin36/xmp#readme","keywords":["iptc","xmp","jpeg","heic","metadata"],"repository":{"type":"git","url":"git+https://github.com/aidin36/xmp.git"},"description":"Read and write XMP metadata from/to various media formats","maintainers":[{"name":"aidin36","email":"aidin@aidinhut.com"}],"readme":"# XMP Javascript package\n\n![NPM Version](https://img.shields.io/npm/v/%40aidin36%2Fxmp) [![codecov](https://codecov.io/github/aidin36/xmp/graph/badge.svg?token=0E601PBV4M)](https://codecov.io/github/aidin36/xmp)\n\nIt can read and write XMP data from/to various file formats.\n\n## Please do not use this to write data\n\nIt's still an under development library. The media file standards are big and\ncomplicated. There are cases that the library can damage the data of your files.\nUse at your own risk!\n\n## Supported Formats\n\n| Format | Read | Write |\n| :----: | :--: | :---: |\n|  JPEG  |  ✓   |   ╳   |\n|  HEIC  |  ✓   |   ✓   |\n\n### Limitations of HEIC\n\nWriting to HEIC format has a few limitations:\n\n- The library cannot handle numbers greater than UINT32 (4294967295) but in\n  some cases HEIC can store UINT64 numbers. If it encounters those larger\n  numbers while reading or writing the file, it will throw an error.\n\n## Installation\n\nInstall it like any other `npm` package. For example:\n\n```bash\nnpm install @aidin36/xmp\n```\n\n## Usage\n\nYou need to read your image as `Uint8Array`. This is the most portable format\n(portable between various Javascript environments). We will provide a few\nexamples below. Then simply pass it to one of the functions provided.\n\nFor example in a `node` environment:\n\n```Typescript\nimport { readXmpFromHeic } from '@aidin36/xmp'\nimport fs from 'fs'\n\nconst fileContent = new Uint8Array(fs.readFileSync('/path/to/file.heic'))\nconst xmp = readXmpFromHeic(fileContent)\n\nif (!xmp) {\n  console.error('Could not find any XMP data in the provided file.')\n}\n\n// xmp is a string\nconsole.log(xmp)\n```\n\n## How to read image as Uint8Array\n\n`Uint8Array` is the most portable structure to store image data. By portable we\nmean, for example, if we were using `ArrayBuffer`, React Native wouldn't be\nable to work with it.\n\nDepending on the Javascript environment you're using, there are multiple ways\nto read an image to an `Uint8Array`. We give you some examples here to get you\nstarted.\n\n_Node_: In `nodejs` you can simply read an image like:\n\n```Typescript\nconst fileContent = new Uint8Array(fs.readFileSync('./path/to/file.heic'))\n```\n\nOr in `React Native`:\n\n```Typescript\nimport { File } from 'expo-file-system/next'\n\nconst fileHandler = new File(fileUrl).open()\nconst fileContent = fileHandler.readBytes(fileHandler.size)\n```\n\nAnd in a browser:\n\n```html\n<input type=\"file\" /><br />\n<img src=\"\" height=\"200\" alt=\"Image preview\" />\n```\n\n```js\nconst preview = document.querySelector('img')\nconst fileInput = document.querySelector('input[type=file]')\n\nfileInput.addEventListener('change', previewFile)\n\nfunction previewFile() {\n  const file = fileInput.files[0]\n  const reader = new FileReader()\n\n  reader.addEventListener(\n    'load',\n    () => {\n      const buf = reader.result\n      const fileContent = new Uint8Array(buf)\n      console.log(`array= ${fileContent}`)\n    },\n    false\n  )\n\n  if (file) {\n    reader.readAsArrayBuffer(file)\n  }\n}\n```\n\nPlease note that these are just some examples. There are other ways to read\nimage to `Uint8Array` that you can choose based on your need.\n\n## API\n\n```Typescript\nexport type XMPNode = string | Record<string, string> | {\n    [k: string]: XMPNode;\n} | Array<string> | Array<XMPNode>\n\nexport type XMP = Record<string, XMPNode>\n\n/**\n * This is the most portable way of reading the data. Because not every\n * Javascript environment supports TextDecoder. In those cases, you can call\n * this function and decode the output using what is available.\n *\n * If your environment has TextDecoder, or if you have a polyfill of it in your\n * application, you can use 'readXmpFromJpegBinary' function to get a decoded\n * string.\n *\n * Note that the output is encoded as UTF-8. Javascript's strings are UTF-16.\n * So you need to decode the output from UTF-8.\n *\n * @param image - Data of the JPEG image in the form of Uint8Array\n * @returns XMP as a UTF-8 byte array, or undefined if no XMP data found in the\n *   provided file.\n */\nexport const readXmpFromJpegAsBinary = (image: Uint8Array): Uint8Array | undefined => jpegExtractXMP(image)\n\n/**\n * Extracts the XMP string from a JPEG file.\n * It returns the string as-is without modifications.\n *\n * Note that your Javascript environment should provide TextDecoder or a\n * polyfill of it.\n *\n * @param image - Data of the JPEG image in the form of Uint8Array\n * @returns XMP as a string, or undefined if no XMP data found in the provided file.\n */\nexport const readXmpFromJpeg = (image: Uint8Array): string | undefined => {\n  if (TextDecoder === undefined) {\n    throw Error('This method needs TextDecoder which is not available in your environment. You can try other methods.')\n  }\n\n  const xmpBinary = jpegExtractXMP(image)\n  if (xmpBinary == null) {\n    return undefined\n  }\n\n  const decoder = new TextDecoder('UTF-8')\n  return decoder.decode(xmpBinary)\n}\n/**\n * Extracts the XMP from a JPEG file, and transforms it to a JS Object.\n * It uses the '@aidin36/xmp2js' for the transformation. You can read the documents\n * of '@aidin36/xmp2js' to learn more about the output format.\n *\n * @param image - Data of the JPEG image in the form of Uint8Array\n * @returns A JS Object, or undefined if no XMP data found in the provided file.\n */\nexport const readXmpFromJpegAsJs = (image: Uint8Array): XMP | undefined => {\n  const xmpString = readXmpFromJpeg(image)\n  if (xmpString == null || xmpString.length === 0) {\n    return undefined\n  }\n  return xmp2js(xmpString)\n}\n\n/**\n * This is the most portable way of reading the data. Because not every\n * Javascript environment supports TextDecoder. In those cases, you can call\n * this function and decode the output using what is available.\n *\n * If your environment has TextDecoder, or if you have a polyfill of it in your\n * application, you can use 'readXmpFromHeic' function to get a decoded string.\n *\n * Note that the output is encoded as UTF-8. Javascript's strings are UTF-16.\n * So you need to decode the output from UTF-8.\n *\n * @param image - Data of the HEIC image in the form of Uint8Array\n * @returns XMP as a UTF-8 byte array, or undefined if no XMP data found in the\n *   provided file.\n */\nexport const readXmpFromHeicAsBinary = (image: Uint8Array): Uint8Array | undefined => heicExtractXmp(image)\n\n/**\n * Extracts the XMP string from a HEIC file.\n * It returns the string as-is without modifications.\n *\n * Note that your Javascript environment should provide TextDecoder.\n *\n * @param image - Data of the HEIC image in the form of Uint8Array\n * @returns XMP as a string, or undefined if no XMP data found in the provided file.\n */\nexport const readXmpFromHeic = (image: Uint8Array): string | undefined => {\n  if (TextDecoder === undefined) {\n    throw Error('This method needs TextDecoder which is not available in your environment. You can try other methods.')\n  }\n\n  const xmpBinary = heicExtractXmp(image)\n  if (xmpBinary == null) {\n    return undefined\n  }\n\n  const decoder = new TextDecoder('UTF-8')\n  return decoder.decode(xmpBinary)\n}\n\n/**\n * Extracts the XMP string from a HEIC file, then converts it to a Javascript\n * Object.\n * It uses the '@aidin36/xmp2js' for the transformation. You can read the documents\n * of '@aidin36/xmp2js' to learn more about the output format.\n *\n * Note that your Javascript environment should provide TextDecoder.\n *\n * @param image - Data of the HEIC image in the form of Uint8Array\n * @returns A JS Object, or undefined if no XMP data found in the provided file.\n */\nexport const readXmpFromHeicAsJs = (image: Uint8Array): XMP | undefined => {\n  const xmpStr = readXmpFromHeic(image)\n  if (xmpStr == null || xmpStr.length === 0) {\n    return undefined\n  }\n  return xmp2js(xmpStr)\n}\n\n/**\n * Writes the XMP data to an image file in HEIC format.\n * This is the most portable overload. Because not every Javascript\n * environment supports TextEncoder. In those cases, you can encode your\n * XMP with what is available and pass it.\n *\n * Note that XMP needs to be in UTF-8 encoding.\n *\n * @param image - Data of the HEIC image in the form of Uint8Array\n * @param xmp - Encoded XMP\n * @returns The modified image\n */\nexport const writeXmpToHeic = (image: Uint8Array, xmp: Uint8Array): Uint8Array => heicWriteOrUpdateXmp(image, xmp)\n\n/**\n * Writes the XMP data to an image file in HEIC format.\n *\n * @param image - Data of the HEIC image in the form of Uint8Array\n * @param xmp - Encoded XMP\n * @returns The modified image\n */\nexport const writeXmpToHeicAsString = (image: Uint8Array, xmp: string): Uint8Array => {\n  if (TextEncoder === undefined) {\n    throw Error('This method needs TextEncoder which is not available in your environment. You can try other methods.')\n  }\n\n  const encoder = new TextEncoder()\n  const encodedXmp = encoder.encode(xmp)\n\n  return heicWriteOrUpdateXmp(image, encodedXmp)\n}\n```\n\n## Copyright\n\nCopyright 2024 - 2025 Aidin Gharibnavaz - https://aidinhut.com\n\nThis program is free software: you can redistribute it and/or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation, either version 3 of the License, or (at your option) any later version.\n\nThis program is distributed in the hope that it will be useful, but WITHOUT ANY WARRANTY; without even the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU Lesser General Public License for more details.\n\nYou should have received a copy of the GNU General Public License along with this program. If not, see <https://www.gnu.org/licenses/>.\n","readmeFilename":"README.md"}