{"id":20955102,"url":"https://github.com/myunisoft/heif-converter","last_synced_at":"2025-05-14T04:33:00.626Z","repository":{"id":244995703,"uuid":"816725366","full_name":"MyUnisoft/heif-converter","owner":"MyUnisoft","description":"High performance HEIF/HEIC -\u003e JPG/PNG convertor (N-API binding to libheif)","archived":false,"fork":false,"pushed_at":"2024-08-13T09:05:06.000Z","size":14228,"stargazers_count":4,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2024-08-14T17:10:57.046Z","etag":null,"topics":["converter","convertor","heic","heif"],"latest_commit_sha":null,"homepage":"","language":"C","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/MyUnisoft.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":"SECURITY.md","support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-06-18T09:34:53.000Z","updated_at":"2024-08-13T09:03:26.000Z","dependencies_parsed_at":"2024-06-18T22:56:05.484Z","dependency_job_id":"7a93d9a0-b274-4045-963f-4b6729e1cdb4","html_url":"https://github.com/MyUnisoft/heif-converter","commit_stats":null,"previous_names":["myunisoft/heif-converter"],"tags_count":11,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MyUnisoft%2Fheif-converter","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MyUnisoft%2Fheif-converter/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MyUnisoft%2Fheif-converter/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/MyUnisoft%2Fheif-converter/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/MyUnisoft","download_url":"https://codeload.github.com/MyUnisoft/heif-converter/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254071350,"owners_count":22009777,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["converter","convertor","heic","heif"],"created_at":"2024-11-19T01:18:00.700Z","updated_at":"2025-05-14T04:32:57.962Z","avatar_url":"https://github.com/MyUnisoft.png","language":"C","funding_links":[],"categories":[],"sub_categories":[],"readme":"\u003cp align=\"center\"\u003e\n\u003cimg src=\"./docs/images/heif-converter.png\"/\u003e\n\u003c/p\u003e\n\n# 🥦 HEIF-Converter\n\u003e This module uses the C APIs libheif to bind it in Node.js using N-API.\n\n## Engine\n### Node\n- Node.js 18.x  \n### Prebuilt binaries\n- MacOS x64 (\u003e= 12)  \n- Windows x64/x86  \n- Linux x64 (glibc \u003e= 2.28, musl \u003e= 1.2.4)\n\n## ⭐ Introduction\n\nThe **libheif** library is a software library used to read and write HEIF (High Efficiency Image Format) files.\n\nHEIF is a file format for images and image sequences (like photos and videos) that offers superior compression compared to traditional formats like JPEG and PNG while maintaining high image quality.\n\nFor more information about the librarie used in this project, you can visit the following links:\n* [libheif](https://github.com/strukturag/libheif/tree/master)\n* [libjpeg](https://github.com/winlibs/libjpeg)\n* [libpng](https://github.com/pnggroup/libpng)\n\n## ❤️ Motivations\n\nWe created this module because, to date, we have not yet found a package that uses Node.js bindings for the libheif C library. Libraries like [heic-convert](https://github.com/catdad-experiments/heic-convert), and others are very interesting but do not allow full utilization of the performance and speed of the C library.\n\nMoreover, this project allows you to use asynchronous methods that will run in an **AsyncWorker**, which will prevent blocking the event loop of your application.\n\n## 💥 Prerequisites\n\nBefore installing **heif-converter**, make sure you have the following tools installed on your machine:\n\n* [**Node.js**](https://nodejs.org/en/download/package-manager/)\n\n## 🎈 Conversion\nThe **heif-converter** package facilitates the conversion of HEIF (High Efficiency Image File Format) images to other formats. However, it's important to note that this package specifically handles static images and does not support animated images. Additionally, metadata and auxiliary images within the HEIF file are not currently supported by the converter. You're welcome to contribute by suggesting improvements or enhancements to its functionality 😃.\n\n## Developer\nIf you wish to contribute or build libheif from source, you can visit [this link](./docs/developer.md).\n\n## 🦴 Installation\n\n```bash\nnpm install @myunisoft/heif-converter\n```\n\n## 🚀 API\n\u003cdetails\u003e\n\u003csummary\u003eversion\u003c/summary\u003e\n\u003cbr\u003e\n\nThe **version** method is used to obtain the version of libheif.\n\n```ts\nfunction version(): string;\n```\n```js\nimport lib from \"../index.js\";\n\nconsole.log(lib.version());\n// 1.17.6\n```\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003etoJpeg\u003c/summary\u003e\n\u003cbr\u003e\n\nThe **toJpeg** method converts the primary image of a HEIC file to **jpg**.\n\u003e Converts only the primary image of the HEIC file.\n\n```ts\ninterface JpegOptions {\n  // 0 to 100.\n  quality?: number;\n}\n\nfunction toJpeg(\n  input: string | Buffer | Readable, \n  options?: JpegOptions\n): Promise\u003cBuffer\u003e;\n```\n```js\n// Import Node.js Dependencies\nimport path from \"node:path\";\n\n// Import Internal Dependencies\nimport lib from \"../index.js\";\n\nconst filePath = path.join(__dirname, \"image.heic\")\nconst jpegBuffer = await lib.toJpeg(filePath, { quality: 20 });\n```\n\u003e The value of the quality option is from 0 to 100. Default 75.\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003etoPng\u003c/summary\u003e\n\u003cbr\u003e\n\nThe **toPng** method converts the primary image of a HEIC file to **png**.\n\u003e Converts only the primary image of the HEIC file.\n\n```ts\nfunction toPng(input: string | Buffer | Readable): Promise\u003cBuffer\u003e;\n```\n```js\n// Import Node.js Dependencies\nimport path from \"node:path\";\n\n// Import Internal Dependencies\nimport lib from \"../index.js\";\n\nconst filePath = path.join(__dirname, \"image.heic\")\nconst pngBuffer = await lib.toPng(filePath, { compression: 5 });\n```\n\u003e The value of the compression option is from 1 to 9. Default 1.\n\n\u003c/details\u003e\n\u003cdetails\u003e\n\u003csummary\u003eextract\u003c/summary\u003e\n\u003cbr\u003e\n\nThe **extract** method allows you to obtain a list of images contained in a HEIC file. Each extracted image has two methods, **toJpeg** and **toPng**, which allow you to convert the image to JPEG or PNG format, respectively, as documented above.\n```ts\ninterface JpegOptions {\n  quality?: number;\n}\n\ninterface PngOptions {\n  compression?: number;\n}\n\ninterface ExtractedImage {\n  toJpeg: (opts?: JpegOptions) =\u003e Promise\u003cBuffer\u003e;\n  toPng: (opts?: PngOptions) =\u003e Promise\u003cBuffer\u003e;\n}\n\nfunction extract(input: string | Buffer | Readable): Promise\u003cExtractedImage[]\u003e;\n```\n```js\n// Import Node.js Dependencies\nimport path from \"node:path\";\n\n// Import Internal Dependencies\nimport lib from \"../index.js\";\n\nconst filePath = path.join(__dirname, \"image.heic\")\nconst images = await lib.extract(filePath);\nfor (image of images) {\n  const jpegBuffer = await image.toJpeg({ quality: 50 });\n}\n```\n\n\u003c/details\u003e\n\n## 📢 Benchmark\n\nThe benchmark is accessible in the ./benchmark folder. You can run the following commands.\n```bash\n$ node ./benchmark/bench.js 1\n# OR\n$ node ./benchmark/bench.js 2\n# OR\n$ node ./benchmark/bench.js 3\n```\nThis benchmark was conducted on a mid-range machine.\n\n#### HEIC file containing an image of 3992*2992.\n\u003cimg src=\"./docs/images/bench1.png\"/\u003e\n\n#### HEIC file containing an image of 2400*1600.\n\u003cimg src=\"./docs/images/bench2.png\"/\u003e\n\n#### HEIC file containing an image of 640*426.\n\u003cimg src=\"./docs/images/bench3.png\"/\u003e","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyunisoft%2Fheif-converter","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fmyunisoft%2Fheif-converter","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fmyunisoft%2Fheif-converter/lists"}