retold-remote 0.0.5 → 0.0.7

package/web-application/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/web-application/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/web-application/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.

package/web-application/docs/server-setup.md

@@ -0,0 +1,262 @@
+# Server Setup and Docker
+
+## Installation
+
+### From npm
+
+```bash
+npm install -g retold-remote
+```
+
+### From source
+
+```bash
+git clone <repo-url>
+cd retold-remote
+npm install
+npm run build
+```
+
+The build step bundles the client-side JavaScript with Quackage and copies assets into `web-application/`.
+
+## Running the Server
+
+### CLI Command
+
+```bash
+retold-remote serve [content-path] [options]
+```
+
+Or using the short alias:
+
+```bash
+rr serve /path/to/media
+```
+
+If `content-path` is omitted, the current directory is served.
+
+### Options
+
+| Flag | Description | Default |
+|------|-------------|---------|
+| `-p, --port [port]` | Port to listen on | Random 7000-7999 |
+| `-H, --hashed-filenames` | Enable hashed filename mode (hides real paths from browser) | Off |
+| `-c, --cache-path [path]` | Root cache directory | `./dist/retold-cache/` |
+| `--cache-thumbnails [path]` | Override thumbnail cache location | `<cache-root>/thumbnails/` |
+| `--cache-archives [path]` | Override archive extraction cache | `<cache-root>/archives/` |
+| `--cache-video-frames [path]` | Override video frame cache | `<cache-root>/video-frames/` |
+| `--cache-audio-waveforms [path]` | Override audio waveform cache | `<cache-root>/audio-waveforms/` |
+
+### Direct Node.js
+
+```bash
+node server.js [content-path]
+```
+
+Default port is `8086` when using `server.js` directly.
+
+### Environment Variables
+
+| Variable | Description | Default |
+|----------|-------------|---------|
+| `PORT` | HTTP port | `8086` (server.js) or random (CLI) |
+| `RETOLD_HASHED_FILENAMES` | Set to `true` to enable hashed filenames | `false` |
+
+### Examples
+
+```bash
+# Serve current directory on port 8086
+node server.js
+
+# Serve a specific folder
+node server.js /mnt/nas/media
+
+# CLI with custom port
+retold-remote serve /mnt/nas/media -p 3000
+
+# Hashed filenames for privacy
+retold-remote serve /mnt/nas/media -H
+
+# Custom cache location (useful for Docker volumes)
+retold-remote serve /media -c /cache
+```
+
+## Configuration
+
+### Settings Persistence
+
+User preferences are stored in the browser via `localStorage` under the key `retold-remote-settings`. These include:
+
+- Theme selection
+- View mode (grid or list)
+- Thumbnail size (small, medium, large)
+- Gallery filter and sort preferences
+- Show hidden files toggle
+- Autoplay video / audio toggles
+- Image fit mode
+- Sidebar state
+- Filter presets
+
+Settings are loaded on page load and saved whenever a preference changes.
+
+### Server Capabilities
+
+On startup the server probes for optional tools and reports availability at `GET /api/media/capabilities`. The Settings panel in the UI shows which tools are detected.
+
+| Tool | Detection Method | Feature |
+|------|-----------------|---------|
+| **sharp** | `require('sharp')` | Image thumbnail generation |
+| **ImageMagick** | `identify --version` | Fallback image thumbnails |
+| **ffmpeg** | `ffmpeg -version` | Video thumbnails, frame extraction, audio waveforms |
+| **ffprobe** | `ffprobe -version` | Media metadata (duration, dimensions, codec, bitrate) |
+| **VLC** | macOS: `/Applications/VLC.app`; Linux: `vlc --version` | External video playback |
+| **7-Zip** | `7z --help` | Archive browsing (rar, 7z, tar.*) |
+| **ebook-convert** | `ebook-convert --version` (Calibre) | MOBI/AZW to EPUB conversion |
+
+Without any optional tools the application still works: images are served directly (no thumbnails), videos play in the browser, and zip/cbz archives use native extraction via yauzl.
+
+### Thumbnail Cache
+
+Thumbnails are cached on disk using a SHA-256 hash of `<filepath>:<mtime>:<width>x<height>`. When the source file is modified the mtime changes, invalidating the cache entry automatically.
+
+Default location: `./dist/retold-cache/thumbnails/`
+
+Default thumbnail size: 200x200, format: webp.
+
+Thumbnails are served with `Cache-Control: public, max-age=86400`.
+
+### Hashed Filenames Mode
+
+When enabled (`-H` flag or `RETOLD_HASHED_FILENAMES=true`), real file paths are never exposed to the browser. Instead, deterministic 10-character hex hashes derived from SHA-256 are used in URLs and API responses. The same path always produces the same hash across server restarts.
+
+## Docker
+
+### Using the Included Dockerfile
+
+A `Dockerfile` is provided in the repository root:
+
+```bash
+docker build -t retold-remote .
+docker run -p 8086:8086 -v /path/to/media:/media retold-remote
+```
+
+### Inline Dockerfile
+
+If you need to create a Dockerfile from scratch, here is a complete working version:
+
+```dockerfile
+FROM node:20-slim
+
+# Install optional tools for full functionality
+RUN apt-get update && apt-get install -y --no-install-recommends \
+    ffmpeg \
+    imagemagick \
+    p7zip-full \
+    calibre \
+    && rm -rf /var/lib/apt/lists/*
+
+WORKDIR /app
+
+# Copy package files and install dependencies
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+# Install sharp (optional image processing)
+RUN npm install sharp || true
+
+# Copy application source and built assets
+COPY source/ source/
+COPY web-application/ web-application/
+COPY css/ css/
+COPY html/ html/
+COPY server.js ./
+
+# Create cache directory
+RUN mkdir -p /cache
+
+# Default port
+ENV PORT=8086
+
+EXPOSE 8086
+
+# Serve /media with cache at /cache
+CMD ["node", "server.js", "/media"]
+```
+
+### Docker Compose
+
+```yaml
+version: "3.8"
+services:
+  retold-remote:
+    build: .
+    ports:
+      - "8086:8086"
+    volumes:
+      - /path/to/media:/media:ro
+      - retold-cache:/cache
+    environment:
+      - PORT=8086
+    restart: unless-stopped
+
+volumes:
+  retold-cache:
+```
+
+### Docker Usage Notes
+
+- Mount your media folder to `/media` (read-only is fine with `:ro`)
+- Mount a volume to `/cache` for persistent thumbnail and frame caches
+- The `node:20-slim` base keeps the image small while the `apt-get` packages add full media processing
+- `calibre` is the largest optional package; omit it if you do not need MOBI/AZW ebook conversion
+- `sharp` is installed separately because it has native bindings that may fail on some architectures; the `|| true` ensures the build continues without it
+
+### Minimal Dockerfile (No Optional Tools)
+
+If you only need basic browsing without thumbnails or media probing:
+
+```dockerfile
+FROM node:20-slim
+
+WORKDIR /app
+
+COPY package.json package-lock.json ./
+RUN npm ci --omit=dev && npm cache clean --force
+
+COPY source/ source/
+COPY web-application/ web-application/
+COPY css/ css/
+COPY html/ html/
+COPY server.js ./
+
+ENV PORT=8086
+EXPOSE 8086
+
+CMD ["node", "server.js", "/media"]
+```
+
+This produces an image under 200MB. Images display directly (no thumbnails), videos play in the browser, and zip/cbz archives use native extraction.
+
+## Archive Browsing
+
+Archives appear as navigable folders in the file browser. Clicking an archive opens it and displays its contents as if they were a regular directory.
+
+**Supported formats:**
+
+| Format | Tool Required |
+|--------|---------------|
+| `.zip`, `.cbz` | None (native yauzl) |
+| `.7z`, `.rar`, `.tar`, `.tar.gz`, `.tar.bz2`, `.tar.xz`, `.tgz`, `.cbr` | 7-Zip |
+
+Files inside archives can be viewed, thumbnailed, and probed just like regular files. Archive contents are extracted to the cache directory on demand.
+
+## VLC Streaming
+
+The VLC integration allows streaming media files to a VLC player running on the server machine. Press `v` in the media viewer to send the current file to VLC.
+
+Setup instructions for macOS, Windows, and Linux are available in the Settings panel under "VLC Protocol Setup". The setup creates a `vlc://` protocol handler that opens files in VLC when triggered from the browser.
+
+**Platform details:**
+- **macOS**: Creates an AppleScript app at `/Applications/VLCProtocol.app` and registers it as a URL handler
+- **Windows**: Registry entry or batch script that maps `vlc://` to the VLC executable
+- **Linux**: Desktop file at `~/.local/share/applications/vlc-protocol.desktop` registered with xdg-mime