{"id":25084828,"url":"https://github.com/zuidvolt/blurhash-avif","last_synced_at":"2026-03-27T04:46:53.817Z","repository":{"id":255441708,"uuid":"851546938","full_name":"ZuidVolt/blurhash-avif","owner":"ZuidVolt","description":"A library to generate BlurHash's and PNG data URLs for AVIF images","archived":false,"fork":false,"pushed_at":"2024-09-06T08:23:13.000Z","size":52,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-11T22:35:51.244Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ZuidVolt.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":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-09-03T09:43:40.000Z","updated_at":"2024-09-06T08:23:16.000Z","dependencies_parsed_at":"2024-09-06T08:14:23.649Z","dependency_job_id":null,"html_url":"https://github.com/ZuidVolt/blurhash-avif","commit_stats":null,"previous_names":["zuidvolt/blurhash-avif"],"tags_count":8,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZuidVolt%2Fblurhash-avif","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZuidVolt%2Fblurhash-avif/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZuidVolt%2Fblurhash-avif/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ZuidVolt%2Fblurhash-avif/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ZuidVolt","download_url":"https://codeload.github.com/ZuidVolt/blurhash-avif/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":237604167,"owners_count":19337258,"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":[],"created_at":"2025-02-07T07:18:48.731Z","updated_at":"2025-10-22T05:30:41.868Z","avatar_url":"https://github.com/ZuidVolt.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# blurhash-avif\n\nA small library for generating **BlurHash** placeholders and lightweight **PNG data URLs** from AVIF images — ideal for fast, progressive image loading in web apps and static sites.\n\n**Disclaimer:** This is an unofficial extension and has no affiliation with the original BlurHash developers. All credit for the BlurHash concept and implementation goes to its creators.\n\nThis README is intentionally concise: every function is fully documented in the code. Here you will find quick installation, practical examples (single-file + batch + decoding) and troubleshooting guidance that is easier to find here than in the docstrings.\n\n---\n\n## Highlights\n\n* Generate BlurHash strings from `.avif` images (compact, text-based placeholders).\n* Produce small PNG data URLs (base64) suitable for inline `src` or `srcset` placeholders.\n* Safe, defensive handling of invalid paths and image issues with explicit exceptions.\n* Batch helpers for directories of AVIFs.\n* Decode BlurHash back into a PNG and save to disk.\n\n---\n\n## Installation\n\n**From PyPI (recommended):**\n\n```bash\npip install blurhash-avif\n```\n\n**From source (editable / dev):**\n\n```bash\ngit clone https://github.com/ZuidVolt/blurhash-avif.git\ncd blurhash-avif\npip install -e .[dev]\n```\n\n### Native image codec requirements\n\n`Pillow` needs AVIF support. The package depends on `pillow-avif-plugin` (the recommended plugin). You may also need the system `libavif` (or equivalent) for AVIF decoding/encoding.\n\n* macOS (Homebrew):\n\n```bash\nbrew install libavif\n```\n\n* Debian/Ubuntu:\n\n```bash\nsudo apt-get install libavif-dev\n```\n\nIf Pillow cannot read AVIF after installing `pillow-avif-plugin`, reinstall Pillow with AVIF extras or ensure the plugin is installed in the same environment.\n\n---\n\n## Quickstart\n\n```python\nimport blurhash_avif as bha\nfrom pathlib import Path\n\navif_path = Path(\"assets/photo.avif\")\n\n# 1) Single-file: BlurHash only\nbh = bha.encode(avif_path, x_components=4, y_components=3)\nprint(\"BlurHash preview:\", bh[:12].upper(), \"…\", \"len=\", len(bh))\n\n# 2) Single-file: PNG data URL (thumbnail) and quick inspect of payload\npdu = bha.encode_pdu(avif_path, max_dimension=64)\n# split and show the first 60 bytes of the base64 payload\nprint(\"PNG payload (head):\", pdu.split(\",\", 1)[1][:60] + \"...\")\n\n# 3) Convenience: both (returns tuple[Optional[str], Optional[str]])\nbh, pdu = bha.encode_blurhash_and_pda(avif_path, x_components=4, y_components=4, max_dimension=48)\nprint(\"got both -\u003e\", bool(bh), bool(pdu))\n\n# 4) Batch: all .avif files in a directory\nresults: dict[str, Optional[str]] = bha.batch_encode(\"assets/\") # returns dict(filename -\u003e blurhash_or_None)\nvalid_files = [name for name, h in results.items() if h]\nprint(\"Valid blurhash files:\", \", \".join(valid_files) or \"\u003cnone\u003e\")\n\n# 5) Decode a blurhash back to disk then check existence\nif bh:\n    bha.decode(\"./decoded/\", bh, filename=\"decoded.png\", width=400, height=300, verbose=True)\n    print(Path(\"./decoded/decoded.png\").exists())\n\n# 6) Decode to PIL image and save with PIL API\nif bh:\n    img = bha.decode_to_pil_format(bh, 200, 150, punch=1.1)\n    out_path = Path(\"./decoded\") / \"from_pil.png\"\n    img.save(out_path)  # PIL.Image.Image.save returns None; we use pathlib to inspect\n    print(out_path.name, \"-\u003e\", out_path.exists())\n```\n\n---\n\n## Example: Using in a web page\n\nUse the PNG data URL as an inline placeholder while the full AVIF loads.\n\n```html\n\u003c!-- small inline placeholder generated with encode_pdu(...) --\u003e\n\u003cimg\n  src=\"data:image/png;base64,iVBORw0KGgoAAAANS...\"\n  data-full-src=\"/images/photo.avif\"\n  alt=\"Example\"\n  width=\"600\"\n  height=\"400\"\n/\u003e\n\n\u003c!-- or use the BlurHash string client-side (if you decode in JS) --\u003e\n\u003cdiv id=\"placeholder\"\u003e\u003c/div\u003e\n\u003cscript\u003e\n  // decode using a BlurHash JS library to paint a canvas until AVIF is ready\n  // blurhashString is the string returned by encode(...)\n\u003c/script\u003e\n```\n\nThis package produces the blurhash string and inline data URL; how you integrate that into your web framework or static generator is up to you.\n\n---\n## Exceptions\n\nThe library raises a small, intentional set of typed exceptions so you can handle errors ergonomically:\n\n* `BlurHashAvifError` — base class for all library exceptions\n* `BlurHashEncodeError` — blurhash encoding failed\n* `AvifPngDataUrlError` — png data URL creation failed\n* `BlurHashDecodeError` — blurhash decoding failed\n* `PathError` — invalid path or I/O issues\n* `ImageSaveError` — failure when saving decoded images\n\nUse `except BlurHashAvifError:` to catch all library-level errors.\n\n---\n\n## Troubleshooting\n\n* *Pillow can't open `.avif` files:* ensure `pillow-avif-plugin` is installed and that your environment's Pillow is compatible with the plugin. Reinstall Pillow after installing the plugin if needed.\n  ```bash\n  pip uninstall pillow\n  pip install \"pillow[avif]\"\n  ```\n* *`MemoryError` or slow performance on huge images:* rely on the library's default resize behavior or pre-scale images.\n* *Unexpected `None` in batch maps:* the library stores `None` for any file that failed to encode; inspect logs or call the functions individually for more detailed exceptions.\n\n---\n\n## Attribution \u0026 License\n\nThis package extends the Python BlurHash library. BlurHash was originally created by Dag Ågren for Wolt. The BlurHash algorithm and official implementations are available at the [BlurHash GitHub repository](https://github.com/woltapp/blurhash).\n\nThis project is licensed under the Apache License, Version 2.0\n\n---\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuidvolt%2Fblurhash-avif","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fzuidvolt%2Fblurhash-avif","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fzuidvolt%2Fblurhash-avif/lists"}