retold-remote 0.0.4 → 0.0.6

package/docs/README.md

@@ -0,0 +1,181 @@
+# Retold Remote
+
+A browser-based media server and NAS file explorer. Point it at a folder and browse images, videos, audio, ebooks, code, and documents through a keyboard-driven gallery interface with 15 built-in themes.
+
+## Quick Start
+
+```bash
+npx retold-remote serve /path/to/media
+```
+
+Or with Docker:
+
+```bash
+docker build -t retold-remote .
+docker run -p 8086:8086 -v /path/to/media:/media retold-remote
+```
+
+Then open `http://localhost:8086` in a browser.
+
+## Features
+
+- **Gallery browser** with grid and list views, thumbnail generation, and lazy loading
+- **Image viewer** with three fit modes, 0.25x-8x zoom, and EXIF orientation support
+- **Video viewer** with action menu, in-browser playback, VLC streaming, and frame explorer
+- **Audio viewer** with waveform visualization, selection-based playback, and segment extraction
+- **eBook reader** for EPUB and MOBI with table of contents and page navigation
+- **Code/text viewer** with syntax highlighting for 30+ languages
+- **PDF viewer** via native browser rendering
+- **Archive browsing** into zip, 7z, rar, tar.gz, cbz, and cbr files as virtual folders
+- **Filtering and sorting** by media type, extension, file size, date, and text search (with regex)
+- **15 themes** from greyscale to retro and cyberpunk
+- **Full keyboard navigation** across every mode
+- **Media type override** to force any file open as image, video, audio, or text (keys 1-4)
+- **Hashed filenames** mode to hide real paths from the browser
+- **VLC protocol handler** setup for macOS, Windows, and Linux
+- **Settings persistence** via localStorage
+
+## Documentation
+
+| Document | Contents |
+|----------|----------|
+| [Server Setup and Docker](server-setup.md) | Installation, CLI options, environment variables, configuration, Docker |
+| [Image Viewer](image-viewer.md) | Fit modes, zoom, keyboard shortcuts, mouse interactions |
+| [Video Viewer](video-viewer.md) | Action menu, playback, frame explorer, timeline, VLC streaming |
+| [Audio Viewer](audio-viewer.md) | Waveform visualization, selection, zoom, segment playback |
+| [eBook Reader](ebook-reader.md) | EPUB/MOBI support, table of contents, page navigation |
+
+## Keyboard Shortcuts (All Modes)
+
+### Global
+
+| Key | Action |
+|-----|--------|
+| `F1` | Help panel |
+| `F9` | Focus sidebar file list |
+| `/` | Search / filter bar |
+| `Esc` | Close overlay / go back |
+
+### Gallery
+
+| Key | Action |
+|-----|--------|
+| Arrow keys | Navigate items |
+| `Enter` | Open selected item |
+| `1` `2` `3` `4` | Open as image / video / audio / text |
+| `Esc` | Go up one folder |
+| `Home` / `End` | Jump to first / last item |
+| `g` | Toggle grid / list view |
+| `f` | Advanced filter panel |
+| `s` | Focus sort dropdown |
+| `x` | Clear all filters |
+| `c` | Settings panel |
+| `d` | Distraction-free mode |
+
+### Media Viewer
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to gallery |
+| Right / `j` | Next file |
+| Left / `k` | Previous file |
+| `1` `2` `3` `4` | View as image / video / audio / text |
+| `Space` | Play / pause |
+| `f` | Fullscreen |
+| `i` | File info overlay |
+| `v` | Stream with VLC |
+| `+` / `-` | Zoom in / out |
+| `0` | Reset zoom |
+| `z` | Cycle fit mode |
+| `d` | Distraction-free mode |
+
+### Video Action Menu
+
+| Key | Action |
+|-----|--------|
+| `Space` / `Enter` | Play in browser |
+| `e` | Explore video frames |
+| `t` | Extract thumbnail |
+| `v` | Stream with VLC |
+
+### Video Explorer
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to video |
+
+### Audio Explorer
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play selection |
+| `+` / `-` | Zoom in / out |
+| `0` | Zoom to fit |
+| `z` | Zoom to selection |
+| `Esc` | Clear selection / back |
+
+## Supported File Formats
+
+### Images
+png, jpg, jpeg, gif, webp, svg, bmp, ico, avif, tiff, tif, heic, heif
+
+### Video
+mp4, webm, mov, mkv, avi, wmv, flv, m4v, ogv, mpg, mpeg, mpe, mpv, m2v, ts, mts, m2ts, vob, 3gp, 3g2, f4v, rm, rmvb, divx, asf, mxf, dv, nsv, nuv, y4m, wtv, swf, dat
+
+### Audio
+mp3, wav, ogg, flac, aac, m4a, wma, oga
+
+### Documents
+pdf, epub, mobi
+
+### Archives
+zip, 7z, rar, tar, tar.gz, tar.bz2, tar.xz, tgz, cbz, cbr
+
+### Code/Text
+js, mjs, cjs, ts, tsx, jsx, py, rb, java, c, cpp, h, hpp, cs, go, rs, php, sh, bash, zsh, pl, r, swift, kt, scala, lua, json, xml, yaml, yml, toml, ini, cfg, conf, env, properties, md, markdown, txt, csv, tsv, log, html, htm, css, scss, sass, less, sql, graphql, gql, makefile, dockerfile, gitignore, editorconfig, htaccess, npmrc, eslintrc, prettierrc
+
+## Themes
+
+**Grey** (pure greyscale): Daylight, Afternoon, Evening, Twilight (default), Night
+
+**Fun** (colorful): Neo-Tokyo, Cyberpunk, Hotdog, 1970s Console, 1980s Console, 1990s Web Site, Early 2000s Web, Synthwave, Solarized Dark, Forest
+
+## Optional Server Tools
+
+These external tools enhance functionality when available on the server:
+
+| Tool | Feature |
+|------|---------|
+| **sharp** (npm) | Fast image thumbnail generation |
+| **ImageMagick** | Fallback image thumbnails |
+| **ffmpeg** | Video thumbnails, frame extraction, audio waveforms |
+| **ffprobe** | Media metadata (duration, resolution, codec) |
+| **7-Zip** (7z) | Archive browsing for rar, 7z, tar.* formats |
+| **VLC** | External video streaming |
+| **ebook-convert** (Calibre) | MOBI to EPUB conversion |
+
+Without these tools the application still works -- images serve directly, videos play in-browser, and zip/cbz archives use native extraction.
+
+## API Endpoints
+
+| Method | Endpoint | Description |
+|--------|----------|-------------|
+| GET | `/api/remote/settings` | Server configuration and capabilities |
+| GET | `/api/filebrowser/list?path=` | Directory listing |
+| PUT | `/api/filebrowser/settings` | Update browser settings (hidden files) |
+| GET | `/api/media/capabilities` | Detected tool availability |
+| GET | `/api/media/thumbnail?path=&width=&height=` | Generate/serve cached thumbnail |
+| GET | `/api/media/probe?path=` | File metadata via ffprobe |
+| GET | `/api/media/folder-summary?path=` | Media type counts for a folder |
+| GET | `/api/media/video-frames?path=&count=` | Extract frames from video |
+| GET | `/api/media/video-frame/:cacheKey/:filename` | Serve extracted frame |
+| GET | `/api/media/video-frame-at?path=&timestamp=` | Extract frame at timestamp |
+| GET | `/api/media/audio-waveform?path=&peaks=` | Audio waveform peak data |
+| GET | `/api/media/audio-segment?path=&start=&end=` | Extract audio segment |
+| GET | `/api/media/ebook-convert?path=` | Convert MOBI to EPUB |
+| GET | `/api/media/ebook/:cacheKey/:filename` | Serve converted ebook |
+| POST | `/api/media/open` | Open file in external player (VLC) |
+
+## License
+
+MIT

package/docs/_cover.md

@@ -0,0 +1,14 @@
+# Retold Remote <small>Documentation</small>
+
+> A browser-based media server and NAS file explorer
+
+Browse images, videos, audio, ebooks, code, and documents through a keyboard-driven gallery interface with 15 built-in themes. Point it at a folder and start exploring.
+
+- **Gallery Browser** — Grid and list views with thumbnails, filtering, sorting, and text search
+- **Media Viewers** — Dedicated viewers for images, video, audio, ebooks, code, and PDFs
+- **Video Explorer** — Extract and browse frames from any video with a visual timeline
+- **Audio Explorer** — Waveform visualization with selection, zoom, and segment playback
+- **Full Keyboard Navigation** — Every feature accessible from the keyboard
+
+[Get Started](server-setup.md)
+[View on GitHub](https://github.com/stevenvelozo/retold-remote)

package/docs/_sidebar.md

@@ -0,0 +1,10 @@
+- [Home](/)
+
+- Getting Started
+  - [Server Setup & Docker](server-setup.md)
+
+- Media Viewers
+  - [Image Viewer](image-viewer.md)
+  - [Video Viewer & Explorer](video-viewer.md)
+  - [Audio Viewer & Explorer](audio-viewer.md)
+  - [eBook Reader](ebook-reader.md)

package/docs/_topbar.md

@@ -0,0 +1,3 @@
+# Retold Remote <small>docs</small>
+
+- [Back to App](/)

package/docs/audio-viewer.md

@@ -0,0 +1,133 @@
+# Audio Viewer and Explorer
+
+The audio viewer provides HTML5 audio playback with an optional waveform explorer for visualizing, selecting, and extracting audio segments.
+
+## Opening an Audio File
+
+- **From the gallery**: select an audio file and press `Enter`, or double-click it
+- **Force any file as audio**: press `3` in the gallery or viewer to open it in the audio viewer regardless of extension
+
+## Audio Player
+
+The viewer shows a centered audio player with the filename and native HTML5 audio controls (play/pause, seek bar, volume, playback speed).
+
+Below the player, action buttons appear:
+
+| Button | Requires | Description |
+|--------|----------|-------------|
+| **Explore Audio** | ffprobe or ffmpeg | Opens the waveform explorer |
+| **Stream with VLC** | -- | Sends the file to VLC on the server |
+
+### Autoplay
+
+Autoplay is off by default. Enable it in Settings > Gallery > Autoplay audio. When enabled, audio begins playing as soon as the player loads.
+
+## Audio Explorer
+
+The audio explorer displays a canvas-based waveform visualization with selection, zoom, and segment extraction.
+
+### Opening the Explorer
+
+- From the audio player, click "Explore Audio"
+- The explorer fetches 2000 peak samples from the server via ffmpeg
+
+### Waveform Display
+
+The main canvas shows the audio waveform as vertical bars. The height of each bar represents the amplitude at that point. A dashed center line marks the zero crossing.
+
+- **Unselected regions** are drawn in the secondary text color
+- **Selected regions** are drawn in the accent color with a semi-transparent highlight behind them
+- A **cursor line** follows the mouse position, displayed in white
+
+### Overview Bar
+
+Below the main waveform, a smaller overview canvas shows the entire audio file. A highlighted viewport indicator box shows which portion of the waveform is currently visible in the main canvas.
+
+Click anywhere on the overview to pan the main view to that position.
+
+### Selection
+
+**Click and drag** on the main waveform to select a time range. The selection is highlighted in the accent color with edge markers.
+
+- If the selection is too small (less than 0.1% of the total duration), it is automatically cleared
+- The selection is shown in both the main canvas and the overview
+
+### Time Display Bar
+
+A bar above the waveform shows three pieces of information:
+
+- **View**: the time range currently visible (e.g., "0:12.3 - 0:45.7")
+- **Selection**: the selected time range and its duration (e.g., "0:20.0 - 0:30.5 (10.5s)"), or "None"
+- **Cursor**: the time position under the mouse, or "--"
+
+Timestamps are formatted as `M:SS.D` (minutes, seconds, tenths of a second) or `H:MM:SS.D` for long files.
+
+### Zoom Controls
+
+| Key / Button | Action |
+|--------------|--------|
+| `+` or `=` | Zoom in (centered) |
+| `-` | Zoom out (centered) |
+| `0` | Zoom to fit (show entire file) |
+| `z` | Zoom to selection (with 5% margin) |
+| Mouse wheel | Zoom at cursor position |
+
+Minimum zoom level is 0.5% of the total duration.
+
+Zooming preserves the center point -- the portion of the waveform under the mouse (for wheel zoom) or the center (for keyboard zoom) stays in place while the view range narrows or widens.
+
+### Playing a Selection
+
+With a selection active, press `Space` or click the Play Selection button to extract and play that audio segment.
+
+The server extracts the segment via ffmpeg and returns it as an MP3 file. A playback bar appears with an HTML5 audio player for the extracted segment.
+
+The extraction endpoint is `/api/media/audio-segment` with `start` and `end` parameters in seconds.
+
+### Info Bar
+
+The explorer shows an info bar with metadata from ffprobe:
+
+| Field | Example |
+|-------|---------|
+| Duration | 3:42 |
+| Sample Rate | 44.1 kHz |
+| Channels | 2 (stereo) |
+| Codec | mp3 |
+| Bitrate | 320 kbps |
+| File Size | 8.7 MB |
+| Peaks | 2000 (ffmpeg) |
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Space` | Play selection |
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Zoom to fit |
+| `z` | Zoom to selection |
+| `Esc` | Clear selection (if any), or go back to audio player |
+
+### Mouse Interactions
+
+| Action | Effect |
+|--------|--------|
+| Click and drag on main waveform | Create/adjust selection |
+| Mouse move on main waveform | Show cursor position in time bar |
+| Mouse wheel on main waveform | Zoom in/out at cursor position |
+| Click on overview bar | Pan main view to that position |
+
+## File Info Overlay
+
+Press `i` while viewing audio to see metadata:
+
+- Size, Duration, Codec, Bitrate, Format, Modified date, Path
+
+## Supported Formats
+
+mp3, wav, ogg, flac, aac, m4a, wma, oga
+
+Browser playback support varies. Most browsers play mp3, wav, ogg, and flac natively. For other formats, use VLC streaming.
+
+Force any file as audio by pressing `3` in the gallery or viewer.

package/docs/ebook-reader.md

@@ -0,0 +1,90 @@
+# eBook Reader
+
+The eBook reader displays EPUB files directly in the browser using epub.js, with support for MOBI files through server-side conversion.
+
+## Opening an eBook
+
+- **From the gallery**: select an `.epub` or `.mobi` file and press `Enter`, or double-click it
+- eBooks are detected by the document type system (pdf, epub, mobi are all in the document category)
+
+## EPUB Files
+
+EPUB files are loaded and rendered directly in the browser using the epub.js library. No server-side processing is required.
+
+### Reading Interface
+
+The reader takes up the full viewer area and displays one page at a time in a single-column layout (no spread/two-page mode). Text is styled to match the active theme:
+
+- Body text uses the theme's primary text color
+- Background matches the theme's primary background
+- Links use the theme's accent color
+- Font: Georgia, Times New Roman, serif
+- Line height: 1.6
+- Padding: 20px horizontal, 40px vertical
+
+### Table of Contents
+
+A sidebar on the left shows the book's table of contents. Each chapter is a clickable button. Subchapters are indented up to two levels.
+
+| Action | Effect |
+|--------|--------|
+| Click a chapter | Jump to that chapter |
+| Click "TOC" button | Toggle the sidebar open/closed |
+
+The TOC sidebar starts collapsed and can be toggled with the TOC button in the controls bar.
+
+### Page Navigation
+
+Controls at the bottom of the reader:
+
+| Button | Action |
+|--------|--------|
+| **TOC** | Toggle table of contents sidebar |
+| **Prev** | Go to previous page |
+| **Next** | Go to next page |
+
+Page navigation moves through the reflowed content. Pages are determined by the viewport size, not by the original book pagination.
+
+## MOBI Files
+
+MOBI files (and AZW format) require server-side conversion to EPUB before they can be displayed. This requires **ebook-convert** from Calibre to be installed on the server.
+
+### Conversion Flow
+
+1. The client requests conversion via `/api/media/ebook-convert?path=<file>`
+2. The server runs `ebook-convert` to produce an EPUB file
+3. The converted EPUB is cached on disk
+4. The client fetches the EPUB from `/api/media/ebook/<cacheKey>/<filename>`
+5. The EPUB is rendered using the same epub.js reader
+
+If ebook-convert is not available, MOBI files show a message explaining that conversion is needed and linking to the Calibre download page.
+
+### Installing Calibre (for MOBI support)
+
+**macOS:**
+```bash
+brew install calibre
+```
+
+**Ubuntu/Debian:**
+```bash
+sudo apt-get install calibre
+```
+
+**Docker:**
+The provided Dockerfile includes Calibre. If using the minimal Dockerfile, add:
+```dockerfile
+RUN apt-get update && apt-get install -y calibre && rm -rf /var/lib/apt/lists/*
+```
+
+## PDF Files
+
+PDF files are rendered using the browser's native PDF viewer in an iframe. No additional tools or libraries are required. The browser provides its own controls for page navigation, zoom, and search.
+
+## Limitations
+
+- MOBI conversion requires Calibre's `ebook-convert` on the server
+- DRM-protected ebooks cannot be read
+- Complex EPUB layouts (fixed-layout EPUBs, heavy CSS) may not render perfectly
+- The reader uses single-page mode only (no two-page spreads)
+- Page numbers shown in the UI correspond to the reflowed content, not the original book pagination

package/docs/image-viewer.md

@@ -0,0 +1,90 @@
+# Image Viewer
+
+The image viewer displays image files with three fit modes, manual zoom, and EXIF orientation support.
+
+## Opening an Image
+
+- **From the gallery**: select a file and press `Enter`, or double-click a tile
+- **Force any file as image**: press `1` in the gallery or viewer to open it in the image viewer regardless of extension
+
+## Fit Modes
+
+Cycle through fit modes by pressing `z`.
+
+### Fit to Window
+
+Scales the image to fill the viewport while preserving aspect ratio (CSS `object-fit: contain` behavior). The image is never larger than the viewport.
+
+### Original if Smaller (default)
+
+Displays the image at its native resolution if it fits within the viewport. If the image is larger than the viewport, it scales down using the same logic as Fit to Window. This avoids upscaling small images.
+
+### Original Size
+
+Always displays at native resolution regardless of viewport size. Large images will overflow and can be scrolled.
+
+When the fit mode changes, a brief overlay indicator appears for 1.2 seconds showing the active mode name.
+
+## Zoom
+
+| Key | Action | Range |
+|-----|--------|-------|
+| `+` or `=` | Zoom in | Up to 8x |
+| `-` | Zoom out | Down to 0.25x |
+| `0` | Reset zoom to 1x | |
+| Click on image | Toggle between 1x and 2x | |
+
+Each zoom step multiplies or divides by 1.25. The zoom level applies on top of the current fit mode calculation.
+
+When zoomed beyond the viewport, the cursor changes to a zoom-out icon and the image can be scrolled. When the image fits, the cursor shows zoom-in.
+
+## Mouse Interactions
+
+- **Click** on the image toggles between 1x and 2x zoom
+- **Scroll** when zoomed to pan the image
+
+## Keyboard Shortcuts
+
+These work while viewing any image:
+
+| Key | Action |
+|-----|--------|
+| `z` | Cycle fit mode (Fit to Window -> Original if Smaller -> Original Size) |
+| `+` / `=` | Zoom in |
+| `-` | Zoom out |
+| `0` | Reset zoom |
+| `f` | Toggle fullscreen |
+| `i` | Toggle file info overlay |
+| Right / `j` | Next file |
+| Left / `k` | Previous file |
+| `v` | Stream with VLC |
+| `d` | Distraction-free mode |
+| `Esc` | Back to gallery |
+
+## File Info Overlay
+
+Press `i` to show metadata about the current image:
+
+- **Size**: file size in KB/MB
+- **Dimensions**: width x height in pixels
+- **Format**: image format
+- **Modified**: last modification date
+- **Path**: file path on the server
+
+The overlay appears in the top-right corner and can be toggled on and off.
+
+## Supported Formats
+
+png, jpg, jpeg, gif, webp, svg, bmp, ico, avif, tiff, tif, heic, heif
+
+Animated GIFs and WebP animations play in the browser natively. SVG files render as vector graphics. HEIC/HEIF support depends on the browser.
+
+## EXIF Orientation
+
+Images are displayed with `image-orientation: from-image`, meaning EXIF rotation data is respected automatically. Portrait photos taken on phones display upright without manual rotation.
+
+## Thumbnails
+
+In the gallery, image thumbnails are generated server-side using sharp (preferred) or ImageMagick (fallback) at 200x200 pixels in webp format. Thumbnails are cached on disk and invalidated when the source file changes.
+
+If no image processing tool is available, the full image is loaded directly.