Metadata-Version: 2.4
Name: navig-generate
Version: 0.4.1
Summary: Generate images, video and audio with your own provider keys, keep the variants you like, and edit them: cut, fx, beats, tonality, sprites. Runs on its own as `navig-generate`; the shared media engine lives in `navig-media-core`.
Author-email: NAVIG Development Team <opensource@navig.run>
License-Expression: Apache-2.0
Project-URL: Homepage, https://navig.run
Project-URL: Documentation, https://navig.run/docs
Keywords: navig,cli,agent,automation,plugin,ai,image,generation
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Utilities
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: navig-sdk>=2.13.0
Requires-Dist: navig-vault>=0.7.0
Requires-Dist: navig-media-core>=0.2.0
Requires-Dist: httpx>=0.24
Requires-Dist: typer>=0.14.0
Requires-Dist: rich>=13.7.0
Requires-Dist: pyyaml>=6.0
Provides-Extra: process
Requires-Dist: Pillow>=10.0; extra == "process"
Provides-Extra: beats
Requires-Dist: numpy>=1.24; extra == "beats"
Provides-Extra: wallpaper
Requires-Dist: Pillow>=10.0; extra == "wallpaper"
Requires-Dist: numpy>=1.24; extra == "wallpaper"
Dynamic: license-file

# navig-generate

<!-- navig:plugin-card:start -->
<!-- Generated by scripts/gen_plugin_catalog.py — edit the plugin's pyproject.toml, not this block. -->

> Generate images, video and audio with your own provider keys, keep the variants you like, and edit them: cut, fx, beats, tonality, sprites. Runs on its own as `navig-generate`; the shared media engine lives in `navig-media-core`.

**Works on its own** — its own CLI, no navig required · v0.4.1 · [PyPI](https://pypi.org/project/navig-generate/)

**On its own** (no navig needed)

```bash
pip install navig-generate
navig-generate --help   # no navig needed
```

**With navig**

```bash
pip install "navig[generate]"
```

<details><summary>Commands</summary>

| Command | What it does |
|---|---|
| `navig generate contact-sheet` | Montage variants into a review contact sheet (Pillow). |
| `navig generate edit` | Instruction-edit an image variant (OpenAI gpt-image). |
| `navig generate eleven change-voice` | Re-speak a recording in another voice, keeping timing and delivery (costs credits). |
| `navig generate eleven fetch` | Download one history item's audio (free — the bytes are already stored). |
| `navig generate eleven history` | List what this key has already generated (free — GET only, costs no credits). |
| `navig generate eleven isolate` | Remove background noise, keep the voice (costs credits). |
| `navig generate eleven stems` | Split a track into stems — returns a zip (costs credits; slow on long files). |
| `navig generate eleven subscription` | Plan, credits and cloning entitlements behind the configured key (free GET). |
| `navig generate eleven transcribe` | Transcribe with ElevenLabs Scribe (costs credits; word timings included). |
| `navig generate eleven voices` | Search the voice library — or list your own voices with `--mine` (free GETs). |
| `navig generate gen` | Generate variant(s) into the active space's refs library. |
| `navig generate ingest` | Pull externally-generated files into the refs library for review (Midjourney, etc.). |
| `navig generate keep` | Promote a staged variant to the kept library. |
| `navig generate license` | Record the license for a variant (provenance). |
| `navig generate list` | List variants in THIS space, newest first (clickable). --all spans every space. |
| `navig generate palette` | Extract a hex palette from reference frames. |
| `navig generate process` | LOCAL pixel pipeline → a game-ready sprite variant (Pillow). |
| `navig generate redesign` | Reference-based img2img redesign (Recraft). |
| `navig generate reject` | Reject a staged variant (retained in .rejected, never deleted). |
| `navig generate rembg` | Remove the background → transparent PNG (Recraft). |
| `navig generate statement` | ⬛ Render a STATEMENT overlay — one line, in Schema's own interface language. |
| `navig generate style list` | List every template id with its kind and title. |
| `navig generate style show` | Print one template: source, prompt, motion (side effects), layout. |
| `navig generate wallpaper generate` | Generate an image, compose it for the display, and set it as the wallpaper. |
| `navig generate wallpaper list` | What this verb has produced, newest first. |
| `navig generate wallpaper make` | Compose a wallpaper file without touching the desktop (works on any OS). |
| `navig generate wallpaper restore` | Put the wallpaper that was active before the last `set`/`generate` back. |
| `navig generate wallpaper schedule` | Rotate the wallpaper on a cadence: set the prompt, the day and the clock. |
| `navig generate wallpaper screens` | List displays with the exact pixel size each wallpaper must be composed for. |
| `navig generate wallpaper set` | Compose an existing image for the display and apply it. |
| `navig generate wallpaper status` | What is on the desktop now, and what this machine supports. |
| `navig generate wallpaper style` | Change how Windows fits the current image to the screen. |

</details>

<!-- navig:plugin-card:end -->

NAVIG **Generate**: make images, video and audio with **your own provider keys**, keep the
variants you like, and edit them. It owns the generation service, the generator clients,
beats, tonality and the sprite pipeline; the shared foundation it and navig run on (video
cut/fx/captions, audio edit, refs library, variant store, provider catalog) is
**`navig-media-core`**, which this package depends on.

## On its own

```bash
pip install navig-generate                # adds the `navig-generate` command
export OPENAI_API_KEY=…                   # or RECRAFT_API_KEY, GEMINI_API_KEY, STABILITY_API_KEY…
navig-generate gen "a red fox, flat vector" --provider openai_gpt_image
navig-generate list                       # short ids; every command accepts them
navig-generate keep 8ab12f25
pip install "navig-generate[process]"     # Pillow: process / palette / contact-sheet
pip install "navig-generate[beats]"       # numpy: beat and tonality detection
```

Variants land in the project you stand in (`<nearest folder with .navig/>/.navig/refs`,
else the current folder) and are recorded in `<data dir>/generated_media.db` — the same
library navig reads, so nothing moves when you install navig later. Keys come from the
environment or the shared encrypted vault (`navig-vault`). ffmpeg must be on `PATH` for
video and audio edits.

## Inside navig

The same commands are `navig generate …` (next to navig's analyse/briefing commands), and
the deck's media screens use this engine. navig's old paths stay identity aliases:
`navig.media.{generation_service,beats,tonality,processing}` and
`navig.tools.{image,video,audio}_generation` from this package, the rest
(`navig.media.{types,refs_library,…}`, `navig.tools.media_providers`) from `navig-media-core`.
Deck screens need navig.

## Wallpapers — `navig generate wallpaper`

The **display** half of generation. `gen` puts a variant in the refs library for review;
this group puts an image on a monitor, at that monitor's exact pixel size. Same engine,
different destination — which is why it is a group under `generate` and not a separate
plugin.

```bash
navig generate wallpaper                           # displays, current image/style, deps
navig generate wallpaper screens                   # exact pixel size per display
navig generate wallpaper generate "a city under a red hexagonal grid" --n 2 --pick 1
navig generate wallpaper set art.png --mode blur   # keep a portrait whole
navig generate wallpaper make art.png --width 3440 --height 1440 -o wall.png
navig generate wallpaper style fit | fill | span | center | stretch | tile
navig generate wallpaper restore                   # back to the previous one (toggles)
pip install "navig-generate[wallpaper]"            # Pillow + numpy
```

Why it composes instead of handing Windows the render: Windows crops a mismatched image
**blindly**, usually through the subject. `--mode cover` crops deliberately, `blur` keeps
the whole image over a blurred bed, `contain` letterboxes on the image's own edge colour;
then it sharpens only what the upscale softened, adds grain (kills 8-bit banding on big
dark gradients), a 10% vignette, an optional `--sky 0.42` falloff toward near-black navy,
and an optional corner mark (`--mark <png> --mark-corner br --mark-height 135`).

Setting is `SystemParametersInfoW(SPI_SETDESKWALLPAPER)` — writing
`HKCU\Control Panel\Desktop\Wallpaper` alone leaves the running session on the old image
until sign-out, and re-saving to the same path is invisible for the same reason. The verb
also pins the fit style and clears `BackgroundType` so a leftover Spotlight/Photos
slideshow cannot override it. Windows-only: `make` still composes anywhere, and says which
size it used.

Files land in `<data dir>/wallpapers/` with `index.json` tracking active/previous; the
composed file you pass with `-o` is used in place instead.
### A wallpaper that rotates itself

Set a prompt and a cadence once; navig generates a fresh wallpaper on that schedule.

```powershell
navig generate wallpaper schedule --prompt "a city under a red hexagonal grid" --every day --at 07:30
navig generate wallpaper schedule --every week --at 06:00      # Mondays
navig generate wallpaper schedule --every off                  # stop rotating
navig generate wallpaper schedule                              # what is set, and the live job
navig generate wallpaper tick                                  # rotate once, now
```

The settings live in navig's config (`generate.wallpaper.*`: prompt, cadence, time, display,
style, mode, mark, candidates) so the CLI and **NAVIG OS** read the same values. The job is a
plain navig cron job (`navig cron list` shows `wallpaper-rotate`), and it runs one fixed
command — `navig generate wallpaper tick` — so changing the prompt never re-registers it.

Where `navig` is not on PATH for the daemon, the job is registered in the runnable form
(cron's `NAVIG_EXEC:` prefix, absolute interpreter) instead of failing at fire time.

**OS surface** — the settings card talks to three deck routes:

| Route | Does |
|---|---|
| `GET /api/deck/generate/wallpaper` | `{rotation: {settings, cadence, expression, job, last_run}, active}` |
| `PUT /api/deck/generate/wallpaper` | save any of `prompt, every, at, monitor, style, mode, mark, n`, then (re-)register |
| `POST /api/deck/generate/wallpaper/run` | rotate once in the background (202), then re-GET for `last_run` |

