retold-remote 0.0.12 → 0.0.15

package/css/retold-remote.css

@@ -2345,6 +2345,31 @@ html, body
 	white-space: nowrap;
 	text-align: center;
 }
+.retold-remote-iex-actions
+{
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	flex-shrink: 0;
+}
+.retold-remote-iex-action-btn
+{
+	padding: 3px 10px;
+	border: 1px solid var(--retold-border);
+	border-radius: 3px;
+	background: transparent;
+	color: var(--retold-text-muted);
+	font-size: 0.75rem;
+	cursor: pointer;
+	transition: color 0.15s, border-color 0.15s;
+	font-family: inherit;
+	white-space: nowrap;
+}
+.retold-remote-iex-action-btn:hover
+{
+	color: var(--retold-text-primary);
+	border-color: var(--retold-accent);
+}
 .retold-remote-iex-info
 {
 	display: flex;
@@ -2504,6 +2529,31 @@ html, body
 	white-space: nowrap;
 	text-align: center;
 }
+.retold-remote-aex-actions
+{
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	flex-shrink: 0;
+}
+.retold-remote-aex-action-btn
+{
+	padding: 3px 10px;
+	border: 1px solid var(--retold-border);
+	border-radius: 3px;
+	background: transparent;
+	color: var(--retold-text-muted);
+	font-size: 0.75rem;
+	cursor: pointer;
+	transition: color 0.15s, border-color 0.15s;
+	font-family: inherit;
+	white-space: nowrap;
+}
+.retold-remote-aex-action-btn:hover
+{
+	color: var(--retold-text-primary);
+	border-color: var(--retold-accent);
+}
 .retold-remote-aex-info
 {
 	display: flex;
@@ -2797,6 +2847,31 @@ html, body
 	white-space: nowrap;
 	text-align: center;
 }
+.retold-remote-vex-actions
+{
+	display: flex;
+	align-items: center;
+	gap: 6px;
+	flex-shrink: 0;
+}
+.retold-remote-vex-action-btn
+{
+	padding: 3px 10px;
+	border: 1px solid var(--retold-border);
+	border-radius: 3px;
+	background: transparent;
+	color: var(--retold-text-muted);
+	font-size: 0.75rem;
+	cursor: pointer;
+	transition: color 0.15s, border-color 0.15s;
+	font-family: inherit;
+	white-space: nowrap;
+}
+.retold-remote-vex-action-btn:hover
+{
+	color: var(--retold-text-primary);
+	border-color: var(--retold-accent);
+}
 .retold-remote-vex-info
 {
 	display: flex;

package/docs/_sidebar.md

@@ -2,6 +2,8 @@
 
 - Getting Started
   - [Server Setup & Docker](server-setup.md)
+  - [Ultravisor Integration](ultravisor-integration.md)
+  - [Ultravisor Beacon Tool Setup](ultravisor-configuration.md)
 
 - Media Viewers
   - [Image Viewer](image-viewer.md)

package/docs/ultravisor-configuration.md

@@ -0,0 +1,212 @@
+# Ultravisor Beacon Tool Setup
+
+This guide covers installing the media processing tools on the machine running the Ultravisor beacon worker. Each tool enables a specific set of capabilities in retold-remote.
+
+## ffmpeg & ffprobe
+
+Used for video thumbnails, frame extraction, audio waveform generation, and media metadata probing.
+
+### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install ffmpeg
+```
+
+Both `ffmpeg` and `ffprobe` are included in the same package.
+
+### macOS
+
+```bash
+brew install ffmpeg
+```
+
+### Windows
+
+1. Download a release build from [gyan.dev/ffmpeg](https://www.gyan.dev/ffmpeg/builds/) — choose the **ffmpeg-release-full** zip.
+2. Extract to a permanent location, e.g. `C:\ffmpeg`.
+3. Add `C:\ffmpeg\bin` to the system PATH:
+   - Open **Settings → System → About → Advanced system settings → Environment Variables**.
+   - Edit the **Path** variable under System variables and add `C:\ffmpeg\bin`.
+4. Open a new terminal and verify:
+
+```cmd
+ffmpeg -version
+ffprobe -version
+```
+
+## ImageMagick
+
+Used as a fallback for image thumbnails and for image format conversion.
+
+### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install imagemagick
+```
+
+By default ImageMagick restricts some operations via a security policy. If you encounter permission errors processing certain formats, edit `/etc/ImageMagick-6/policy.xml` (or the ImageMagick-7 equivalent) and adjust the relevant policy lines.
+
+### macOS
+
+```bash
+brew install imagemagick
+```
+
+### Windows
+
+1. Download the installer from [imagemagick.org/script/download.php](https://imagemagick.org/script/download.php) — choose the **Win64 dynamic** installer.
+2. During installation, check **Add application directory to your system path** and **Install legacy utilities (e.g. convert)**.
+3. Open a new terminal and verify:
+
+```cmd
+magick --version
+```
+
+On Windows, use `magick convert` instead of bare `convert` to avoid conflicts with the built-in Windows `convert` command.
+
+## dcraw
+
+Used for converting raw camera images (CR2, NEF, ARW, DNG, ORF, RW2, etc.).
+
+### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install dcraw
+```
+
+### macOS
+
+```bash
+brew install dcraw
+```
+
+### Windows
+
+1. Download the precompiled binary from [dechifro.org/dcraw](https://www.dechifro.org/dcraw/) or build from source.
+2. Place `dcraw.exe` in a directory on your PATH, e.g. `C:\tools`.
+3. Add that directory to the system PATH if it is not already present.
+4. Verify:
+
+```cmd
+dcraw
+```
+
+dcraw prints usage information when run without arguments.
+
+## audiowaveform
+
+Used for generating audio waveform peak data displayed in the audio viewer.
+
+### Ubuntu / Debian
+
+```bash
+sudo add-apt-repository ppa:chris-needham/ppa
+sudo apt update
+sudo apt install audiowaveform
+```
+
+If the PPA is not available for your Ubuntu version, build from source:
+
+```bash
+sudo apt install cmake libmad0-dev libid3tag0-dev libsndfile1-dev \
+  libgd-dev libboost-filesystem-dev libboost-program-options-dev \
+  libboost-regex-dev
+git clone https://github.com/bbc/audiowaveform.git
+cd audiowaveform
+mkdir build && cd build
+cmake ..
+make
+sudo make install
+```
+
+### macOS
+
+```bash
+brew install audiowaveform
+```
+
+If the formula is not in the default tap:
+
+```bash
+brew tap bbc/audiowaveform
+brew install audiowaveform
+```
+
+### Windows
+
+audiowaveform does not provide official Windows binaries. Options:
+
+1. **WSL** (recommended) — install Ubuntu via WSL and follow the Ubuntu instructions above. Run the beacon worker inside WSL.
+2. **Build from source** — requires CMake, Visual Studio, and the Boost, libmad, libsndfile, and libgd libraries. See the [audiowaveform GitHub repo](https://github.com/bbc/audiowaveform) for build instructions.
+
+## ebook-convert (Calibre)
+
+Used for converting MOBI and AZW ebooks to EPUB format for the in-browser reader.
+
+### Ubuntu / Debian
+
+```bash
+sudo apt update
+sudo apt install calibre
+```
+
+This installs the full Calibre suite. Only `ebook-convert` is used by the beacon.
+
+### macOS
+
+```bash
+brew install --cask calibre
+```
+
+After installation, the `ebook-convert` command-line tool is at:
+
+```
+/Applications/calibre.app/Contents/MacOS/ebook-convert
+```
+
+Add it to your PATH or create a symlink:
+
+```bash
+sudo ln -s /Applications/calibre.app/Contents/MacOS/ebook-convert /usr/local/bin/ebook-convert
+```
+
+### Windows
+
+1. Download and install Calibre from [calibre-ebook.com/download_windows](https://calibre-ebook.com/download_windows).
+2. The default install path is `C:\Program Files\Calibre2`.
+3. Add `C:\Program Files\Calibre2` to the system PATH.
+4. Verify:
+
+```cmd
+ebook-convert --version
+```
+
+## Verifying the Beacon
+
+After installing tools, start the beacon and check its reported capabilities. The Ultravisor server exposes `GET /Beacon/Capabilities` which lists the aggregate capabilities of all connected beacons.
+
+You can also verify each tool individually:
+
+```bash
+ffmpeg -version
+ffprobe -version
+convert --version      # ImageMagick (use 'magick --version' on Windows)
+dcraw                  # prints usage
+audiowaveform --help
+ebook-convert --version
+```
+
+retold-remote only dispatches commands for tools the beacon has available. Missing tools simply mean those operations fall back to local processing on the NAS.
+
+## Quick Reference
+
+| Tool | Ubuntu | macOS | Windows |
+|------|--------|-------|---------|
+| ffmpeg / ffprobe | `apt install ffmpeg` | `brew install ffmpeg` | Download from gyan.dev, add to PATH |
+| ImageMagick | `apt install imagemagick` | `brew install imagemagick` | Installer from imagemagick.org |
+| dcraw | `apt install dcraw` | `brew install dcraw` | Download binary, add to PATH |
+| audiowaveform | PPA or build from source | `brew install audiowaveform` | WSL or build from source |
+| ebook-convert | `apt install calibre` | `brew install --cask calibre` + symlink | Calibre installer, add to PATH |

package/docs/ultravisor-integration.md

@@ -0,0 +1,140 @@
+# Ultravisor Integration
+
+retold-remote can offload heavy media processing to a remote machine running an Ultravisor beacon worker. This is useful when the server (e.g. a NAS) has limited CPU and RAM but needs to process large video files, raw camera images, audio waveforms, and ebook conversions.
+
+## How It Works
+
+When configured, retold-remote dispatches shell commands (ffmpeg, ffprobe, dcraw, ImageMagick, audiowaveform, ebook-convert) to a beacon worker via HTTP instead of running them locally. The beacon downloads the source file from retold-remote's content API, executes the command, and returns the result as base64-encoded data.
+
+```
+NAS (retold-remote)                 Fast Machine (Ultravisor)
+┌──────────────────────┐            ┌──────────────────────┐
+│ Request → Check Cache│            │ Ultravisor Server    │
+│   ↓ (miss)           │   HTTP     │   └─ Beacon Worker   │
+│ Dispatch command  ───┼──────────►│      1. Download src │
+│                      │            │      2. Run command  │
+│ ◄─ base64 result  ◄──┼────────────┤      3. Return output│
+│   ↓                  │            │                      │
+│ Decode → Cache       │            └──────────────────────┘
+│ Serve response       │
+│                      │
+│ ↓ (dispatch fails)   │
+│ Local fallback       │
+└──────────────────────┘
+```
+
+All caching, metadata, and storage remain on the NAS. Only the tool execution changes.
+
+## Setup
+
+### 1. Start Ultravisor on the Fast Machine
+
+Install and run the Ultravisor server with a beacon worker:
+
+```bash
+# On the fast machine
+npm install ultravisor
+node ultravisor-server.js --port 55555
+```
+
+The beacon worker must have the processing tools installed:
+
+| Tool | Used For |
+|------|----------|
+| **ffmpeg** | Video thumbnails, frame extraction, audio waveform generation |
+| **ffprobe** | Media metadata (duration, dimensions, codec, bitrate) |
+| **dcraw** | Raw camera image conversion (CR2, NEF, ARW, etc.) |
+| **ImageMagick** | Image format conversion, thumbnails |
+| **audiowaveform** | Audio waveform peak data |
+| **ebook-convert** | MOBI/AZW to EPUB conversion (from Calibre) |
+
+Only install the tools you need. The beacon reports its capabilities and retold-remote only dispatches commands for tools the beacon has available.
+
+### 2. Configure retold-remote
+
+Pass two settings when starting the server:
+
+| Setting | Description | Example |
+|---------|-------------|---------|
+| `UltravisorURL` | URL of the Ultravisor server | `http://192.168.1.100:55555` |
+| `ContentAPIURL` | URL where the beacon can reach retold-remote's content API | `http://192.168.1.50:8086` |
+
+```bash
+# CLI
+retold-remote serve /mnt/media \
+  --ultravisor-url http://192.168.1.100:55555 \
+  --content-api-url http://192.168.1.50:8086
+
+# Or via server setup options
+node server.js /mnt/media
+```
+
+The `ContentAPIURL` must be reachable from the beacon machine over the network. This is the URL the beacon uses to download source files before processing them.
+
+### 3. Verify Connection
+
+On startup, retold-remote pings the Ultravisor server and logs whether beacons are available. Check the server logs for:
+
+```
+Ultravisor Dispatcher: connection check passed, beacons available.
+```
+
+If no `UltravisorURL` is configured, the dispatcher is disabled and all processing runs locally, identical to the default behavior.
+
+## Offloaded Operations
+
+The following operations are dispatched to the beacon when available:
+
+| Service | Operation | Command |
+|---------|-----------|---------|
+| **MediaService** | Video thumbnails | `ffmpeg -ss ... -vframes 1 -vf scale=WxH ...` |
+| **MediaService** | Image thumbnails (ImageMagick path) | `convert ... -thumbnail WxH ...` |
+| **MediaService** | Media probing | `ffprobe -v quiet -print_format json ...` |
+| **VideoFrameService** | Frame extraction | `ffmpeg -ss T -vframes 1 -vf scale=WxH ...` |
+| **VideoFrameService** | Video probing | `ffprobe -v quiet -print_format json ...` |
+| **AudioWaveformService** | Audio probing | `ffprobe -v quiet -print_format json ...` |
+| **EbookService** | MOBI/AZW conversion | `ebook-convert source.mobi output.epub` |
+| **ImageService** | Raw conversion (dcraw) | `dcraw -c -w "{SourcePath}" \| convert ppm:- jpeg:"{OutputPath}"` |
+| **ImageService** | Image conversion (ImageMagick) | `convert "{SourcePath}" -quality 92 "{OutputPath}"` |
+
+## File Transfer
+
+Since the beacon worker runs on a separate machine without shared filesystem access, files are transferred over HTTP:
+
+1. **Source download**: The beacon downloads the source file from retold-remote's content API (`ContentAPIURL + '/content/' + relativePath`) before executing the command.
+2. **Result return**: The beacon base64-encodes the output file and includes it in the HTTP response.
+3. **Decode and cache**: retold-remote decodes the base64 data and stores it in the local cache (Parime storage).
+
+The `{SourcePath}` and `{OutputPath}` placeholders in commands are automatically replaced with local staging paths on the beacon.
+
+## Affinity and Download Caching
+
+When the same source file is used for multiple operations (e.g. generating a video thumbnail, then extracting frames from the same video), the beacon caches the downloaded file using an affinity key. The download only happens once per file.
+
+Affinity keys are derived from the relative file path. All operations on the same source file reuse the cached download. Affinity staging is cleaned up when the beacon shuts down or when the affinity TTL expires (default: 1 hour).
+
+## Fallback Behavior
+
+Every dispatched operation has automatic fallback to local processing:
+
+- If `UltravisorURL` is not configured, all operations run locally (no behavior change).
+- If the Ultravisor server is unreachable, operations fall back to local tools.
+- If the beacon returns an error, the operation falls back to local execution.
+- If no beacons are registered, dispatch returns an error and local processing takes over.
+
+This means the Ultravisor integration is purely additive. Removing the configuration or shutting down the Ultravisor server does not break any functionality.
+
+## Synchronous Dispatch
+
+retold-remote uses synchronous HTTP dispatch (`POST /Beacon/Work/Dispatch`). The HTTP connection stays open until the beacon completes the work item. This avoids polling complexity and works well for the request-response pattern of thumbnail generation and media probing.
+
+The default timeout is 5 minutes (300,000 ms). Individual operations may specify shorter timeouts.
+
+## Troubleshooting
+
+| Symptom | Cause | Fix |
+|---------|-------|-----|
+| All operations run locally | `UltravisorURL` not configured or Ultravisor unreachable | Check URL and network connectivity |
+| Beacon downloads fail | `ContentAPIURL` not reachable from beacon machine | Verify network route between machines |
+| Timeouts on large files | File too large for default timeout | Increase `TimeoutMs` in Ultravisor settings |
+| Beacon missing capabilities | Required tools not installed on beacon machine | Install ffmpeg, dcraw, etc. on the beacon |

package/package.json

@@ -1,98 +1,123 @@
 {
-	"name": "retold-remote",
-	"version": "0.0.12",
-	"description": "Retold Remote - NAS media browser with gallery views and keyboard navigation",
-	"main": "source/Pict-RetoldRemote-Bundle.js",
-	"bin": {
-		"retold-remote": "source/cli/RetoldRemote-CLI-Run.js",
-		"rr": "source/cli/RetoldRemote-CLI-Run.js"
-	},
-	"files": [
-		"source/",
-		"web-application/",
-		"html/",
-		"css/",
-		"docs/",
-		"README.md",
-		"LICENSE"
-	],
-	"scripts": {
-		"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"
-	},
-	"author": "steven velozo <steven@velozo.com>",
-	"license": "MIT",
-	"dependencies": {
-		"@xmldom/xmldom": "^0.8.11",
-		"dcraw": "^1.0.3",
-		"epubjs": "^0.3.93",
-		"exifr": "^7.1.3",
-		"fable": "^3.1.63",
-		"fable-serviceproviderbase": "^3.0.19",
-		"node-unrar-js": "^2.0.2",
-		"orator": "^6.0.4",
-		"orator-serviceserver-restify": "^2.0.9",
-		"parime": "^1.0.3",
-		"pdf-parse": "^1.1.1",
-		"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.8",
-		"yauzl": "^3.2.0"
-	},
-	"optionalDependencies": {
-		"@img/sharp-wasm32": "^0.34.5",
-		"sharp": "^0.34.5"
-	},
-	"devDependencies": {
-		"quackage": "^1.0.61"
-	},
-	"copyFilesSettings": {
-		"whenFileExists": "overwrite"
-	},
-	"copyFiles": [
-		{
-			"from": "./html/*",
-			"to": "./web-application/"
-		},
-		{
-			"from": "./css/**",
-			"to": "./web-application/css/"
-		},
-		{
-			"from": "./node_modules/pict/dist/pict.min.js",
-			"to": "./web-application/js/"
-		},
-		{
-			"from": "./node_modules/pict/dist/pict.min.js.map",
-			"to": "./web-application/js/"
-		},
-		{
-			"from": "./node_modules/jszip/dist/jszip.min.js",
-			"to": "./web-application/js/"
-		},
-		{
-			"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/"
-		}
-	]
+    "name": "retold-remote",
+    "version": "0.0.15",
+    "description": "Retold Remote - NAS media browser with gallery views and keyboard navigation",
+    "main": "source/Pict-RetoldRemote-Bundle.js",
+    "bin": {
+        "retold-remote": "source/cli/RetoldRemote-CLI-Run.js",
+        "rr": "source/cli/RetoldRemote-CLI-Run.js"
+    },
+    "files": [
+        "source/",
+        "web-application/",
+        "html/",
+        "css/",
+        "docs/",
+        "README.md",
+        "LICENSE"
+    ],
+    "scripts": {
+        "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/*_tests.js",
+        "prepack": "npm run build",
+        "tests": "npx mocha -u tdd --exit -R spec --grep",
+        "coverage": "npx nyc --reporter=lcov --reporter=text-lcov npx mocha -- -u tdd -R spec",
+        "examples": "npx quack examples",
+        "docs": "npx quack prepare-docs ./docs -d ./modules",
+        "docs-serve": "npx quack docs-serve ./docs"
+    },
+    "author": "steven velozo <steven@velozo.com>",
+    "license": "MIT",
+    "dependencies": {
+        "@xmldom/xmldom": "^0.8.11",
+        "dcraw": "^1.0.3",
+        "epubjs": "^0.3.93",
+        "exifr": "^7.1.3",
+        "fable": "^3.1.63",
+        "fable-serviceproviderbase": "^3.0.19",
+        "node-unrar-js": "^2.0.2",
+        "orator": "^6.0.4",
+        "orator-serviceserver-restify": "^2.0.9",
+        "parime": "^1.0.3",
+        "pdf-parse": "^1.1.1",
+        "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.8",
+        "yauzl": "^3.2.0"
+    },
+    "optionalDependencies": {
+        "@img/sharp-wasm32": "^0.34.5",
+        "sharp": "^0.34.5"
+    },
+    "devDependencies": {
+        "puppeteer": "^24.0.0",
+        "quackage": "^1.0.63"
+    },
+    "copyFilesSettings": {
+        "whenFileExists": "overwrite"
+    },
+    "copyFiles": [
+        {
+            "from": "./html/*",
+            "to": "./web-application/"
+        },
+        {
+            "from": "./css/**",
+            "to": "./web-application/css/"
+        },
+        {
+            "from": "./node_modules/pict/dist/pict.min.js",
+            "to": "./web-application/js/"
+        },
+        {
+            "from": "./node_modules/pict/dist/pict.min.js.map",
+            "to": "./web-application/js/"
+        },
+        {
+            "from": "./node_modules/jszip/dist/jszip.min.js",
+            "to": "./web-application/js/"
+        },
+        {
+            "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/"
+        }
+    ],
+    "mocha": {
+        "diff": true,
+        "extension": [
+            "js"
+        ],
+        "package": "./package.json",
+        "reporter": "spec",
+        "slow": "75",
+        "timeout": "5000",
+        "ui": "tdd",
+        "spec": "test/*_tests.js",
+        "watch-files": [
+            "source/**/*.js",
+            "test/**/*.js"
+        ],
+        "watch-ignore": [
+            "lib/vendor"
+        ]
+    }
 }