# Midjourney Viewer for Obsidian

Browse a folder of downloaded Midjourney images inside Obsidian — with the
**full prompt** for every image, search, a lightbox, and galleries you can
embed in your notes.

Prompts are read from the metadata Midjourney embeds in PNG files, so you get
the complete prompt even when the filename is truncated. A filename parser
covers everything else.

**Website:** [spencerleeclark.com/midjourney-viewer](https://www.spencerleeclark.com/midjourney-viewer/) ·
**Install:** in Obsidian, Settings → Community plugins → Browse → search "Midjourney Viewer"

> If this plugin is useful to you, consider [buying me a coffee](https://buymeacoffee.com/spencerleeclark) ☕

## Features

- **Gallery view** of your whole library, opened from the ribbon or a command
- **Full prompts from PNG metadata** (`Description` / `Author` tEXt chunks) —
  Midjourney caps filenames at ~100 characters, so filename-only tools lose
  long prompts; this plugin doesn't
- **Filename parsing** as a fallback for other formats, recovering prompt,
  normalized parameters (`--ar 16 9` → `--ar 16:9`), job UUID, variant and username
- **Search** with phrases, exclusions, and parameter queries (`"--ar 16:9" city -neon`)
- **Lightbox** with keyboard navigation, clickable parameter chips, copy
  prompt/command/path, insert into note, open externally
- **Note embeds**: ` ```midjourney``` ` code blocks render grid, masonry,
  strip, slideshow or random galleries — built through a dialog with live
  preview counts, never by memorizing syntax (hover an embed and click ✎ to edit it)
- **Fast**: thumbnails are generated lazily and cached; metadata is read once
  per file and cached; full-size images are streamed one at a time

## Installation

**From Obsidian** (recommended): Settings → Community plugins → Browse → search
"Midjourney Viewer" → Install, then Enable. The [website](https://www.spencerleeclark.com/midjourney-viewer/)
has a one-click *Install in Obsidian* button that opens the same screen.

**Manual**: download `main.js`, `manifest.json`, and `styles.css` from the
[latest release](https://github.com/spencer1975/obsidian-midjourney-viewer/releases/latest)
into `<your vault>/.obsidian/plugins/midjourney-viewer/`, then enable it in
Settings → Community plugins.

## Setup

1. In the plugin's settings, set **Library folder** to where your Midjourney
   downloads live (a `Browse…` button is provided).
2. Open the viewer from the ribbon (image icon) or the command
   *Open Midjourney viewer*. Right-clicking the ribbon icon opens a menu with
   the other actions: insert a gallery embed, rescan the library.

## Search

Terms are ANDed across prompt, parameters, filename, job ID and username.

| Query | Meaning |
|---|---|
| `neon city` | contains both words |
| `"old fisherman"` | exact phrase |
| `city -neon` | has `city`, not `neon` |
| `--niji` | has the niji parameter |
| `"--ar 16:9"` | that exact aspect ratio |

Press `/` to focus the search box, `Esc` to clear it.

## Lightbox

Click any tile. `←` / `→` move between images, `Esc` closes.
Parameter chips are clickable — they search for that parameter.

Actions: copy prompt, copy full command, copy path, insert into the open note,
open externally, show in folder.

## Embedding galleries in notes

Run the command **Insert gallery embed** (also in the ribbon icon's
right-click menu): pick a subfolder from a dropdown, choose a style, drag
sliders for size, and watch a live count of matching images. To change a
gallery later, hover it and click the **✎** button — the same dialog opens
pre-filled and rewrites the block for you.

Under the hood each gallery is a ` ```midjourney``` ` code block you can also
write by hand:

````
```midjourney
folder: portraits
style: masonry
size: 180
limit: 12
```
````

All keys are optional — an empty block embeds the whole library as a grid.

| Key | Values | Meaning |
|---|---|---|
| `folder` | `portraits` or `a, b` | Subfolder(s) of the library, comma-separated. Nested and absolute paths work. Blank = whole library. |
| `style` | `grid` \| `masonry` \| `strip` \| `slideshow` \| `random` | Grid crops square; masonry keeps aspect; strip scrolls horizontally; slideshow shows one at a time; random shows one random image per render. |
| `size` | px, default `160` (`340` for slideshow) | Tile size, strip height, or slideshow height. |
| `limit` | number, `0` = all | Cap on images shown (after sorting). |
| `sort` | `newest` \| `oldest` \| `name` \| `name-desc` \| `largest` \| `prompt` \| `random` | Order of images. |
| `match` | e.g. `--ar 16:9 -neon` | Filter with the same query syntax as the viewer search box. |
| `captions` | `hover` \| `always` \| `off` | Prompt overlay on tiles / caption under the slideshow. |
| `interval` | seconds, `0` = manual | Slideshow auto-advance; pauses while hovered. |

## How caching works

- Thumbnails are generated as tiles scroll into view and cached as JPEGs in
  `thumbs/` inside the plugin folder, keyed by a hash of the image path.
- PNG metadata is cached in `meta.json`, keyed by file size and mtime, so each
  image is only opened once.
- Both caches can be cleared from the plugin settings.

## Development

The plugin is plain JavaScript with no build step — `main.js` is the source.
Internals are exposed via `module.exports.__test` for offline testing in Node
with a stubbed `obsidian` module.

`tools/make-sample-library.py` generates a folder of fake Midjourney downloads
(realistic filenames, gradient PNGs) for testing without a real library:

```
python3 tools/make-sample-library.py ~/Pictures/midjourney-sample
```

## Disclaimer

This is an unofficial community plugin, not affiliated with or endorsed by
Midjourney, Inc. It only reads image files you have already downloaded.

## License

[MIT](LICENSE)