retold-remote 0.0.4 → 0.0.6

package/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

package/docs/video-viewer.md

@@ -0,0 +1,134 @@
+# Video Viewer and Explorer
+
+The video viewer provides an action menu for choosing how to interact with a video, inline browser playback, VLC streaming, and a frame explorer for scrubbing through video content visually.
+
+## Opening a Video
+
+- **From the gallery**: select a video file and press `Enter`, or double-click it
+- **Force any file as video**: press `2` in the gallery or viewer to open it in the video viewer regardless of extension
+
+## Video Action Menu
+
+When a video is opened, an action menu appears instead of playing immediately. The menu shows the filename and a preview frame extracted from the video midpoint.
+
+### Menu Options
+
+| Key | Option | Description |
+|-----|--------|-------------|
+| `Space` / `Enter` | **Play in Browser** | Plays the video inline with HTML5 `<video>` controls |
+| `e` | **Explore Video Frames** | Opens the frame explorer (requires ffmpeg) |
+| `t` | **Extract Thumbnail** | Extracts a single frame from the midpoint |
+| `v` | **Stream with VLC** | Sends the file to VLC on the server machine |
+
+The preview frame in the menu is loaded automatically from the server. If ffmpeg is not available, the Explore and Thumbnail options are hidden.
+
+Navigation shortcuts still work while the menu is open:
+
+| Key | Action |
+|-----|--------|
+| Right / `j` | Skip to next file |
+| Left / `k` | Skip to previous file |
+| `Esc` | Back to gallery |
+
+## In-Browser Playback
+
+Pressing `Space` or `Enter` replaces the action menu with an HTML5 video player. The player has native browser controls for play/pause, seeking, volume, and fullscreen.
+
+Below the player, a **stats bar** shows:
+
+- **Duration** (formatted as mm:ss)
+- **Resolution** (width x height)
+- **Codec** (e.g., h264, hevc, vp9)
+- **Bitrate** (in kbps or Mbps)
+- **File Size** (formatted)
+
+The stats bar also includes buttons to jump to the Video Explorer or stream with VLC.
+
+### Autoplay
+
+Autoplay is off by default. Enable it in Settings > Gallery > Autoplay video. When enabled, videos begin playing as soon as the player loads.
+
+## Video Explorer
+
+The video explorer extracts multiple frames from a video and displays them in a grid, letting you scrub through content visually without playing the video.
+
+### Opening the Explorer
+
+- From the video action menu, press `e`
+- From the video stats bar during playback, click "Explore Video"
+
+### Frame Grid
+
+Frames are displayed in a responsive grid. Each frame card shows:
+
+- The extracted frame image
+- A timestamp label (e.g., "1:23")
+- A frame index number
+
+Double-click any frame to open it in a full-screen preview overlay.
+
+### Controls
+
+At the top of the explorer:
+
+| Control | Description |
+|---------|-------------|
+| Frame count dropdown | Choose 10, 20, 40, 60, or 100 frames (default: 20) |
+| Full-res checkbox | Extract frames at 1920x1080 instead of 640x360 |
+| Refresh button | Re-extract frames with current settings |
+
+### Info Bar
+
+Below the controls, an info bar displays video metadata:
+
+- Duration
+- Resolution
+- Codec
+- File size
+- Number of extracted frames
+
+### Timeline Bar
+
+Below the frame grid, a timeline bar shows the video duration with markers at each extracted frame's position. The timeline also shows markers for any custom frames you extract.
+
+**Click anywhere on the timeline** to extract a frame at that exact timestamp. The extracted frame appears in the grid in chronological order, styled with a dashed border to distinguish it from the evenly-spaced frames.
+
+### Frame Preview
+
+Double-click any frame in the grid to open a full-screen preview overlay showing the frame at full size.
+
+In the preview:
+
+| Key | Action |
+|-----|--------|
+| Left / `k` | Previous frame |
+| Right / `j` | Next frame |
+| `Esc` | Close preview |
+
+The Back button in the preview header also closes it. Navigation moves through all frames (regular and custom) in chronological order.
+
+### Keyboard Shortcuts
+
+| Key | Action |
+|-----|--------|
+| `Esc` | Back to video viewer |
+
+## VLC Streaming
+
+Press `v` from the action menu, stats bar, or viewer to send the current video to VLC running on the server. This is useful for files in formats the browser cannot play natively.
+
+VLC protocol setup instructions are available in Settings > VLC Protocol Setup, with platform-specific guides for macOS, Windows, and Linux.
+
+## File Info Overlay
+
+Press `i` while viewing a video to see metadata:
+
+- Size, Duration, Resolution, Codec, Bitrate, Format, Modified date, Path
+
+## Supported Formats
+
+**Natively recognized extensions**: 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
+
+**Browser playback support** varies by format. Most browsers play mp4 (h264), webm (vp8/vp9), and ogg natively. For other formats, use VLC streaming or the frame explorer.
+
+**Force any file as video** by pressing `2` in the gallery or viewer to bypass extension detection. This is useful for misnamed files (e.g., `.avii` instead of `.avi`).

package/html/docs.html

@@ -0,0 +1,59 @@
+<!doctype html>
+<html lang="en">
+	<head>
+		<meta charset="utf-8">
+		<meta http-equiv="X-UA-Compatible" content="IE=edge">
+		<meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+		<meta name="description" content="Retold Remote Documentation">
+
+		<title>Retold Remote - Documentation</title>
+
+		<!-- Docuserve base stylesheet -->
+		<link href="css/docuserve.css" rel="stylesheet">
+		<!-- PICT Dynamic View CSS Container -->
+		<style id="PICT-CSS"></style>
+
+		<!-- Load the PICT library -->
+		<script src="js/pict.min.js" type="text/javascript"></script>
+		<!-- Bootstrap the Application -->
+		<script type="text/javascript">
+			Pict.safeOnDocumentReady(function()
+			{
+				// Intercept AppData.Docuserve creation to inject DocsBaseURL
+				// before pict-docuserve starts fetching markdown files.
+				var _origInit = PictDocuserve.prototype.onAfterInitializeAsync;
+				PictDocuserve.prototype.onAfterInitializeAsync = function(fCallback)
+				{
+					var _appData = this.pict.AppData;
+					// One-shot setter: when onAfterInitializeAsync assigns
+					// AppData.Docuserve, modify DocsBaseURL before loadCatalog runs.
+					Object.defineProperty(_appData, 'Docuserve',
+					{
+						configurable: true,
+						enumerable: true,
+						set: function(pValue)
+						{
+							pValue.DocsBaseURL = 'docs/';
+							Object.defineProperty(_appData, 'Docuserve',
+							{
+								configurable: true,
+								enumerable: true,
+								writable: true,
+								value: pValue
+							});
+						}
+					});
+					return _origInit.call(this, fCallback);
+				};
+				Pict.safeLoadPictApplication(PictDocuserve, 2);
+			});
+		</script>
+	</head>
+	<body>
+		<!-- The root container for the Pict application -->
+		<div id="Docuserve-Application-Container"></div>
+
+		<!-- Load the Docuserve PICT Application Bundle -->
+		<script src="js/pict-docuserve.min.js" type="text/javascript"></script>
+	</body>
+</html>

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "retold-remote",
-	"version": "0.0.4",
+	"version": "0.0.6",
 	"description": "Retold Remote - NAS media browser with gallery views and keyboard navigation",
 	"main": "source/Pict-RetoldRemote-Bundle.js",
 	"bin": {
@@ -12,12 +12,12 @@
 		"web-application/",
 		"html/",
 		"css/",
-		"server.js",
+		"docs/",
 		"README.md",
 		"LICENSE"
 	],
 	"scripts": {
-		"start": "node server.js",
+		"start": "node source/cli/RetoldRemote-CLI-Run.js serve",
 		"build": "npx quack build && npx quack copy",
 		"test": "npx mocha -u tdd --exit --timeout 30000 test/*_test.js",
 		"prepack": "npm run build"
@@ -28,23 +28,25 @@
 		"epubjs": "^0.3.93",
 		"fable": "^3.1.63",
 		"fable-serviceproviderbase": "^3.0.19",
-		"orator": "^6.0.3",
+		"orator": "^6.0.4",
 		"orator-serviceserver-restify": "^2.0.9",
-		"pict": "^1.0.356",
+		"parime": "^1.0.3",
+		"pict": "^1.0.357",
 		"pict-application": "^1.0.33",
+		"pict-docuserve": "^0.0.32",
 		"pict-provider": "^1.0.12",
 		"pict-section-code": "^1.0.3",
 		"pict-section-filebrowser": "^0.0.2",
 		"pict-service-commandlineutility": "^1.0.19",
 		"pict-view": "^1.0.67",
-		"retold-content-system": "^1.0.4",
+		"retold-content-system": "^1.0.8",
 		"yauzl": "^3.2.0"
 	},
 	"optionalDependencies": {
 		"sharp": "^0.34.5"
 	},
 	"devDependencies": {
-		"quackage": "^1.0.59"
+		"quackage": "^1.0.61"
 	},
 	"copyFilesSettings": {
 		"whenFileExists": "overwrite"
@@ -69,6 +71,18 @@
 		{
 			"from": "./node_modules/epubjs/dist/epub.min.js",
 			"to": "./web-application/js/"
+		},
+		{
+			"from": "./node_modules/pict-docuserve/dist/pict-docuserve.min.js",
+			"to": "./web-application/js/"
+		},
+		{
+			"from": "./node_modules/pict-docuserve/css/docuserve.css",
+			"to": "./web-application/css/"
+		},
+		{
+			"from": "./docs/*.md",
+			"to": "./web-application/docs/"
 		}
 	]
 }