sony-hlg-to-ultrahdr 0.2.0
Import Sony Alpha HLG stills and convert them into Ultra HDR JPEGs automatically.
Requires Python: >=3.9
Keywords: sony, alpha, hlg, ultrahdr, photography, import

# Sony HLG to Ultra HDR Importer

Automate your Sony Alpha ingest workflow: copy new Hybrid Log Gamma (HLG) stills and clips from the SD card, convert `.HIF` frames into Ultra HDR JPEGs, and resume where you left off on the next card import.

## Why This Exists
Modern Sony Alpha bodies (A1, A7R V, A7S III, A6700, FX30, ZV-E1, and more) can capture stills in HLG as `.HIF` files. Converting those files to viewable Ultra HDR JPEGs typically requires a handful of command-line tools and careful bookkeeping. This package wraps the process in a single command:

- Detect a mounted Sony SD card (or use a manual path on any platform).
- Copy any new stills (`.HIF`, `.ARW`) and clips (`.MP4`, `.MXF`, `.M2TS`) into timestamped export folders.
- Invoke the bundled conversion helper to turn fresh HLG stills into Ultra HDR JPEGs.
- Track the last imported filenames in a SQLite database so repeat runs focus only on new material.

## Features
- **Multi-camera awareness**: Works with current Sony Alpha, FX, and ZV series bodies that write HLG `.HIF`.
- **Safe imports**: Leaves existing exports untouched; only copies media newer than the last recorded filename.
- **Ultra HDR conversion**: Bundles `convert_hif_to_ultrahdr.sh` so you can feed captures straight to Google Photos or Android devices that understand Ultra HDR.
- **Portable state**: Stores progress in `~/.sony_hlg_ultrahdr/media_progress.db` by default, with overrides for shared workflows.
- **Dual entry points**: Installs the new `sony-hlg-to-ultrahdr` CLI and keeps the legacy `sony-media-import` name for existing scripts.

## Installation
Install from a source checkout or a downloaded wheel:

```bash
python -m pip install sony-hlg-to-ultrahdr
```

This installs the package and exposes the command-line entry points.

## External Dependencies
The conversion pipeline relies on a few native tools. Install them before running the importer.

### Required binaries
- `ffmpeg` (must include the `zscale` filter)
- `ffprobe`
- `exiftool`
- `ultrahdr_app` built from Google’s [libultrahdr](https://github.com/google/libultrahdr) project

### Quick install snippets
macOS (Homebrew):
```bash
brew install ffmpeg exiftool
```

Ubuntu / Debian:
```bash
sudo apt update
sudo apt install ffmpeg exiftool
```

Build `ultrahdr_app`:
```bash
git clone https://github.com/google/libultrahdr.git
cd libultrahdr
cmake -S . -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build --target ultrahdr_app -j
```
Point the importer at `build/ultrahdr_app` using `--ultrahdr-app` or the `HLG_ULTRAHDR_APP` environment variable.

## Quick Start
```bash
sony-hlg-to-ultrahdr \
  --image-dest ~/Pictures/sony/imports/images \
  --video-dest ~/Pictures/sony/imports/videos \
  --ultra-dest ~/Pictures/sony/imports/images_ultrahdr
```

- If you omit `--sd-root`, the tool attempts to auto-detect a mounted card (macOS `/Volumes/*`). Supply the flag on Linux/Windows or when multiple cards are attached.
- Export folders default to `export_YYMMDD[_NN]` relative to the current working directory if you skip the destination flags.

## Configuration Reference

| Purpose | CLI flag | Environment variables |
| --- | --- | --- |
| SD card mount point | `--sd-root` | `HLG_ULTRAHDR_SD_ROOT`, `AUTO_IMPORT_SD_ROOT` |
| Still destination | `--image-dest` | — |
| Video destination | `--video-dest` | — |
| Ultra HDR destination | `--ultra-dest` | — |
| SQLite database path | `--db-path` | `HLG_ULTRAHDR_DB_PATH`, `AUTO_IMPORT_DB_PATH` |
| State directory (default parent for DB) | derived from `--db-path` | `HLG_ULTRAHDR_STATE_DIR`, `AUTO_IMPORT_STATE_DIR` |
| Conversion script | `--convert-script` | `HLG_ULTRAHDR_CONVERT_SCRIPT`, `AUTO_IMPORT_CONVERT_SCRIPT` |
| `ultrahdr_app` binary | `--ultrahdr-app` | `HLG_ULTRAHDR_APP`, `AUTO_IMPORT_ULTRAHDR_APP` |

Use either the CLI flags or the environment variables; flags take precedence.

## Developing and Packaging
Run the CLI module directly from the source tree:
```bash
python -m sony_hlg_ultrahdr.cli --help
```

Build distribution artifacts:
```bash
python -m pip install --upgrade build twine  # once per environment
python -m build                              # produces dist/*.tar.gz and dist/*.whl
```

Publish to PyPI or TestPyPI with Twine:
```bash
# TestPyPI
python -m twine upload --repository testpypi dist/*

# PyPI
python -m twine upload dist/*
```
Export `TWINE_USERNAME=__token__` and `TWINE_PASSWORD=<token>` or configure `~/.pypirc` before uploading.

## License
Update `pyproject.toml` with the correct author and license metadata before distributing the package. If you plan to share binaries of `ultrahdr_app`, review Google’s libultrahdr licensing terms as well.