marten/QUICKSTART.md

# marten — Quickstart

A 5-minute guide to get marten running and showing you photos.

---

## 1. Get the binary

You have three options, fastest first.

### Option A — use the prebuilt binary

```bash
cd marten
./bin/marten
```

The binary at `bin/marten` is a stripped release build for x86-64 Linux.
It should run on any modern distribution with GTK3, libxcb, and fontconfig
installed (most desktops already have these).

### Option B — install to your PATH

```bash
cp bin/marten ~/.local/bin/
marten
```

Make sure `~/.local/bin` is in your `$PATH` (most modern distros handle
this automatically; if not, add `export PATH="$HOME/.local/bin:$PATH"`
to your `~/.bashrc` or `~/.zshrc`).

### Option C — build from source

```bash
# Prerequisites (Arch)
sudo pacman -S --needed rust gtk3 wayland-protocols libx11 libxcb fontconfig

# Build
git clone http://git.dcos.net/dcosnet/marten.git
cd marten
cargo run --release
```

The first build takes ~5 minutes (lots of GUI dependencies to compile).
Subsequent builds are incremental and fast.

---

## 2. Open a folder

When marten starts, you'll see a dark window with "No image — press O to
open a folder" in the center.

Press `O` (the letter, not the number zero).

Pick a folder that has some images in it. Marten will scan it, filter out
unsupported extensions, sort lexicographically, and show the first image.

The top thumbnail strip will populate over the next few seconds as
thumbnails decode in the background.

---

## 3. Navigate

| Action | How |
|---|---|
| Next photo | `→` arrow key, or `L`, or scroll wheel **down** |
| Previous photo | `←` arrow key, or `H`, or scroll wheel **up** |
| First photo | `G` (uppercase — vim convention) |
| Last photo | `g` (lowercase) |
| Random photo in this folder | `z`, or click the **shuffle** button in the toolbar |
| Random photo in folder tree | `Shift+Z` |
| Jump to specific image | click its thumbnail in the top strip |

The scroll wheel works anywhere in the image area — you do not need to
position the cursor over the image. This is the ristretto-style behavior
marten was designed around.

Whenever the current image changes (scroll, arrow key, random jump, or
thumbnail click), the top thumbnail strip auto-scrolls to keep the
current entry centered — like a video editor's playhead on a timeline.

---

## 4. Zoom and pan

| Action | How |
|---|---|
| Fit to window | `0` (zero), or click the **fit** icon in the bottom toolbar |
| 100% (actual size) | `1`, or click the **1:1** icon |
| Zoom in | `+`, or `Ctrl+↑`, or click **+** |
| Zoom out | `-`, or `Ctrl+↓`, or click **−** |
| Pan when zoomed | scroll wheel, or drag the scrollbars |

In fit-to-window mode (default), the scroll wheel navigates between
photos. In any zoom mode (100% or custom), the scroll wheel pans the
image. This prevents accidental navigation while you are trying to look
at a zoomed detail.

Each zoom step multiplies the factor by 1.1 (zoom in) or divides by 1.1
(zoom out), producing smooth, graceful changes that do not overshoot.

---

## 5. Rotate

| Action | How |
|---|---|
| Rotate 90° clockwise | `R`, or click the rotate-CW icon, or right-click → Rotate 90° CW |
| Rotate 90° counter-clockwise | `Shift+R`, or click the rotate-CCW icon, or right-click → Rotate 90° CCW |

Rotation is non-destructive — the original file is never modified. The
pixel buffer is rotated in memory and the image is re-rendered. Switching
to another photo resets rotation to 0°.

---

## 6. Right-click menu

Right-click anywhere in the image area. You will get a gpicview-style menu
with 12 actions:

- **Open With…** — launches `xdg-open` to hand the file to your system's
  default image handler.
- **Copy Path** — copies the absolute file path to the clipboard.
- **Copy Image** — copies the actual pixel data to the clipboard (so you
  can paste into GIMP, Krita, etc.).
- **Copy to Pictures** — copies the file to `~/Pictures/`. If a file with
  the same name already exists there, marten appends `_1`, `_2`, etc.
- **Rotate 90° CW / CCW** — same as the toolbar buttons.
- **Set as Wallpaper** — tries `gsettings` (GNOME) first, falls back to
  `feh` for standalone window managers.
- **Move to Trash** — sends the file to the system trash via the `trash`
  crate. Removes it from the navigator and loads the next image.
- **Delete Permanently** — `std::fs::remove_file()`. Bypasses trash
  entirely. Use with care.
- **Properties** — opens the EXIF properties panel (see step 7).
- **Export folder as video…** — opens the video export dialog (see step 8).
- **About marten** — opens the About dialog.

---

## 7. Random navigation, sidebar, slideshow, EXIF panel

Random navigation is new in v0.4.0; the sidebar, slideshow, and EXIF
panel arrived in v0.3.0 and are grouped here for browsing-mode
reference.

### Random navigation (`z` and `Shift+Z`)

Press `z` to jump to a random image in the current folder. Press
`Shift+Z` to jump to a random image anywhere in the current folder's
parent tree — marten walks the parent directory recursively, collects
every supported image across all subfolders, and picks one at random.
If the chosen image lives in a different subfolder, marten switches to
that folder automatically. Both actions are step-aware: subsequent
arrow/scroll navigation continues sequentially from the new position.

Click the **shuffle** button in the bottom toolbar (between Next and
Fit) for the same effect as pressing `z`.

### Folder tree sidebar (`Tab`)

Press `Tab` to slide in a 240px left panel. It lists the sibling folders
of your current location — every child of the parent directory that
contains at least one supported image — each with an image count. Click
any entry to switch folders. Press `Tab` again to dismiss. The sidebar
hides automatically in fullscreen.

### Slideshow mode (`s`)

Press `s` to start an automatic slideshow. Marten advances to the next
photo every three seconds via an `iced::time::every` subscription.
Press `s` again or `Escape` to stop. A toast confirms the start and stop
of the slideshow.

### EXIF properties panel (`i`)

Press `i` (or right-click → Properties) to open a modal with the full
file metadata:

- Filename, path, dimensions, format, file size
- Camera make and model
- Lens model
- ISO, aperture (f-number), shutter speed, focal length
- Timestamp
- GPS coordinates
- Orientation flag

EXIF is parsed with `kamadak-exif`. Files without EXIF (PNG, SVG,
OpenEXR, screenshots, etc.) still show the file-info rows. Press
`Escape` or click outside the card to dismiss.

---

## 8. Export a folder as video

Right-click → **Export folder as video…** opens a modal that turns the
current folder into a `.webm` slideshow with an audio track of your
choice.

1. The dialog shows the image count and the folder name.
2. Click **Select audio file** and pick an audio file (`.mp3`, `.wav`,
   `.ogg`, `.flac`, `.aac`, or `.m4a`).
3. Click **Select output file** and pick a destination `.webm` path.
4. Choose a codec: **VP9** (`libvpx-vp9`, broad compatibility, faster
   encode) or **AV1** (`libaom-av1`, better compression, slower encode).
5. Set the seconds-per-image duration (default 3.0).
6. Click **Export**. ffmpeg runs in a background thread via
   `tokio::task::spawn_blocking`; the dialog shows "Exporting…" then
   "Export complete!" or an error message.

Marten invokes ffmpeg with the concat demuxer and a temporary file
list. ffmpeg must be installed and on `$PATH` — if it is missing, the
dialog reports "ffmpeg not found. Install ffmpeg to use video export."

---

## 9. Keyboard shortcuts (full list)

| Action | Default bindings |
|---|---|
| Next photo | `→` or `L` |
| Previous photo | `←` or `H` |
| First photo | `g` |
| Last photo | `G` |
| Random photo (same folder) | `z` |
| Random photo (folder tree) | `Shift+Z` |
| Zoom in | `+` or `Ctrl+↑` |
| Zoom out | `-` or `Ctrl+↓` |
| Fit to window | `0` |
| Actual size (100%) | `1` |
| Rotate CW | `r` |
| Rotate CCW | `Shift+R` |
| Toggle sidebar | `Tab` |
| Toggle slideshow | `s` |
| Toggle fullscreen | `F11` |
| Toggle chrome (minimal mode) | `Shift+F` |
| Open folder | `o` |
| Copy to Pictures | `Shift+Home` |
| Delete permanently | `Shift+Delete` |
| Properties (EXIF panel) | `i` |
| About marten | `a` |
| Quit | `q` or `Ctrl+Q` |
| Dismiss overlay (menu/modal) | `Escape` |

All of these are configurable — see step 10.

---

## 10. Customize the keymap

Copy the default keymap to your config directory:

```bash
mkdir -p ~/.config/marten
cp config/keymap.toml ~/.config/marten/keymap.toml
$EDITOR ~/.config/marten/keymap.toml
```

The format is a flat TOML map. Each action takes a list of bindings
(you can bind multiple keys to the same action):

```toml
next_photo = ["Right", "l", "Space"]
prev_photo = ["Left", "h", "Backspace"]
```

Modifier syntax: `Ctrl+Shift+R`, `Alt+Tab`, `Logo+L` (logo = Super/Windows/Cmd).
Modifiers are case-insensitive; the key name itself is case-sensitive
(`g` and `G` are different bindings, following vim convention).

Restart marten after editing. Unknown keys are warned about in the
console (run with `RUST_LOG=info` to see warnings) but do not crash.

---

## 11. Fullscreen / minimal mode

Press `F11` (or `Shift+F`) to toggle fullscreen. In this mode:

- The thumbnail strip, sidebar, toolbar, and status bar all hide.
- The image fills the entire window.
- A small floating hint at the top-center of the screen ("Press F11 to
  exit fullscreen") reminds you how to leave.
- All keyboard shortcuts still work.
- Right-click still works.

Press `F11` or `Shift+F` again to exit fullscreen.

---

## 12. Quit

Press `Q` or `Ctrl+Q`. Or close the window normally.

---

## Troubleshooting

**"No supported images in that folder"** — the folder exists but contains
no files with extensions marten recognizes. Check that your files end in
`.png`, `.jpg`, `.jpeg`, `.gif`, `.webp`, `.avif`, `.bmp`, `.ico`, `.cur`,
`.jxl`, `.tif`, `.tiff`, `.svg`, `.svgz`, or `.exr`.

**The window opens but is blank / shows a black screen** — your GPU
driver may not support Vulkan. Check the console output for wgpu errors.
Marten requires a Vulkan-capable GPU; NVIDIA, AMD, and Intel drivers
all work.

**Anti-list modal appears** — you tried to open a `.heic`, `.cr3`, `.nef`,
`.arw`, `.psd`, `.dng`, or Apple Live Photo file. Marten deliberately
refuses these formats. The modal explains why and suggests an open
alternative (e.g. convert HEIC to AVIF).

**Thumbnails are slow to load** — marten decodes thumbnails on a tokio
`spawn_blocking` thread pool at 72px using nearest-neighbor filtering.
For folders with thousands of images, only the current ±15 are cached
at any time. If your disk is slow (network mount, spinning rust), the
first scroll through a fresh folder may take a moment.

**"ffmpeg not found" in the export dialog** — video export shells out to
ffmpeg. Install it via your distribution package manager
(`sudo pacman -S ffmpeg` on Arch, `sudo apt install ffmpeg` on Debian,
`sudo dnf install ffmpeg` on Fedora) and ensure the `ffmpeg` binary is
on `$PATH`.

**`RUST_LOG=warn marten`** — shows warnings (malformed keymap, decode
errors) in the console. `RUST_LOG=info` adds informational messages
(startup, adapter selection). `RUST_LOG=debug` is very noisy.

---

## Where to go next

- `README.md` — full project overview, format support tiers, license.
- `DECISION.md` — architectural decision records (why iced, why dark-only,
  why the anti-list, etc.).
- `BLOG.md` — v0.4.0 release notes and design rationale.
- `config/keymap.toml` — the default keymap, fully commented.