317 lines
11 KiB
Markdown
317 lines
11 KiB
Markdown
# marten — Quickstart
|
||
|
||
A 5-minute guide to get marten running and showing you photos.
|
||
|
||
---
|
||
|
||
### 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.
|