retold-remote 0.0.4 → 0.0.6

package/source/views/PictView-Remote-VideoExplorer.js

@@ -400,7 +400,7 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		// Header
 		tmpHTML += '<div class="retold-remote-vex-header">';
 		tmpHTML += '<button class="retold-remote-vex-nav-btn" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].goBack()" title="Back to video (Esc)">&larr; Back</button>';
-		tmpHTML += '<div class="retold-remote-vex-title">Video Explorer &mdash; ' + this._escapeHTML(tmpFileName) + '</div>';
+		tmpHTML += '<div class="retold-remote-vex-title">Video Explorer &mdash; ' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpFileName) + '</div>';
 		tmpHTML += '</div>';
 
 		// Info bar (populated after frames load)
@@ -503,18 +503,18 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		if (tmpInfoBar)
 		{
 			let tmpInfoHTML = '';
-			tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Duration</span> <span class="retold-remote-vex-info-value">' + this._escapeHTML(tmpData.DurationFormatted) + '</span></span>';
+			tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Duration</span> <span class="retold-remote-vex-info-value">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpData.DurationFormatted) + '</span></span>';
 			if (tmpData.VideoWidth && tmpData.VideoHeight)
 			{
 				tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Resolution</span> <span class="retold-remote-vex-info-value">' + tmpData.VideoWidth + '&times;' + tmpData.VideoHeight + '</span></span>';
 			}
 			if (tmpData.Codec)
 			{
-				tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Codec</span> <span class="retold-remote-vex-info-value">' + this._escapeHTML(tmpData.Codec) + '</span></span>';
+				tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Codec</span> <span class="retold-remote-vex-info-value">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpData.Codec) + '</span></span>';
 			}
 			if (tmpData.FileSize)
 			{
-				tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Size</span> <span class="retold-remote-vex-info-value">' + this._formatFileSize(tmpData.FileSize) + '</span></span>';
+				tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Size</span> <span class="retold-remote-vex-info-value">' + this.pict.providers['RetoldRemote-FormattingUtilities'].formatFileSize(tmpData.FileSize) + '</span></span>';
 			}
 			tmpInfoHTML += '<span class="retold-remote-vex-info-item"><span class="retold-remote-vex-info-label">Frames</span> <span class="retold-remote-vex-info-value">' + tmpData.FrameCount + '</span></span>';
 
@@ -541,9 +541,9 @@ class RetoldRemoteVideoExplorerView extends libPictView
 				let tmpFrameURL = '/api/media/video-frame/' + tmpData.CacheKey + '/' + tmpFrame.Filename;
 
 				tmpGridHTML += '<div class="retold-remote-vex-frame" id="retold-vex-frame-' + i + '" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].selectFrame(' + i + ')" ondblclick="pict.views[\'RetoldRemote-VideoExplorer\'].openFrameFullsize(' + i + ')">';
-				tmpGridHTML += '<img src="' + tmpFrameURL + '" alt="Frame at ' + this._escapeHTML(tmpFrame.TimestampFormatted) + '" loading="lazy">';
+				tmpGridHTML += '<img src="' + tmpFrameURL + '" alt="Frame at ' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpFrame.TimestampFormatted) + '" loading="lazy">';
 				tmpGridHTML += '<div class="retold-remote-vex-frame-info">';
-				tmpGridHTML += '<span class="retold-remote-vex-frame-timestamp">' + this._escapeHTML(tmpFrame.TimestampFormatted) + '</span>';
+				tmpGridHTML += '<span class="retold-remote-vex-frame-timestamp">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpFrame.TimestampFormatted) + '</span>';
 				tmpGridHTML += '<span class="retold-remote-vex-frame-index">#' + (tmpFrame.Index + 1) + '</span>';
 				tmpGridHTML += '</div>';
 				tmpGridHTML += '</div>';
@@ -586,7 +586,7 @@ class RetoldRemoteVideoExplorerView extends libPictView
 			let tmpSelectedClass = (i === this._selectedFrameIndex) ? ' selected' : '';
 			tmpHTML += '<div class="retold-remote-vex-timeline-marker' + tmpSelectedClass + '" '
 				+ 'style="left:' + tmpPercent.toFixed(2) + '%;" '
-				+ 'title="' + this._escapeHTML(tmpFrame.TimestampFormatted) + '" '
+				+ 'title="' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpFrame.TimestampFormatted) + '" '
 				+ 'onclick="event.stopPropagation(); pict.views[\'RetoldRemote-VideoExplorer\'].selectFrame(' + i + ')">'
 				+ '</div>';
 		}
@@ -600,13 +600,13 @@ class RetoldRemoteVideoExplorerView extends libPictView
 				let tmpPercent = (tmpCustom.Timestamp / tmpData.Duration) * 100;
 				tmpHTML += '<div class="retold-remote-vex-timeline-marker custom" '
 					+ 'style="left:' + tmpPercent.toFixed(2) + '%;" '
-					+ 'title="' + this._escapeHTML(tmpCustom.TimestampFormatted) + '">'
+					+ 'title="' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpCustom.TimestampFormatted) + '">'
 					+ '</div>';
 			}
 		}
 
 		tmpHTML += '</div>';
-		tmpHTML += '<span class="retold-remote-vex-timeline-label">' + this._escapeHTML(tmpData.DurationFormatted) + '</span>';
+		tmpHTML += '<span class="retold-remote-vex-timeline-label">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpData.DurationFormatted) + '</span>';
 
 		tmpTimeline.innerHTML = tmpHTML;
 		tmpTimeline.style.display = '';
@@ -729,13 +729,13 @@ class RetoldRemoteVideoExplorerView extends libPictView
 				if (tmpPlaceholder)
 				{
 					let tmpFrameURL = '/api/media/video-frame/' + tmpData.CacheKey + '/' + pResult.Filename;
-					let tmpEscFilename = tmpSelf._escapeHTML(pResult.Filename).replace(/'/g, "\\'");
-					let tmpEscTimestamp = tmpSelf._escapeHTML(pResult.TimestampFormatted).replace(/'/g, "\\'");
+					let tmpEscFilename = tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pResult.Filename).replace(/'/g, "\\'");
+					let tmpEscTimestamp = tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pResult.TimestampFormatted).replace(/'/g, "\\'");
 					tmpPlaceholder.ondblclick = function() { pict.views['RetoldRemote-VideoExplorer'].openCustomFrameFullsize(tmpEscFilename, tmpEscTimestamp); };
 					tmpPlaceholder.style.cursor = 'pointer';
-					tmpPlaceholder.innerHTML = '<img src="' + tmpFrameURL + '" alt="Frame at ' + tmpSelf._escapeHTML(pResult.TimestampFormatted) + '" loading="lazy">'
+					tmpPlaceholder.innerHTML = '<img src="' + tmpFrameURL + '" alt="Frame at ' + tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pResult.TimestampFormatted) + '" loading="lazy">'
 						+ '<div class="retold-remote-vex-frame-info">'
-						+ '<span class="retold-remote-vex-frame-timestamp">' + tmpSelf._escapeHTML(pResult.TimestampFormatted) + '</span>'
+						+ '<span class="retold-remote-vex-frame-timestamp">' + tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pResult.TimestampFormatted) + '</span>'
 						+ '<span class="retold-remote-vex-frame-index">custom</span>'
 						+ '</div>';
 				}
@@ -748,9 +748,9 @@ class RetoldRemoteVideoExplorerView extends libPictView
 				let tmpPlaceholder = document.getElementById(tmpPlaceholderId);
 				if (tmpPlaceholder)
 				{
-					tmpPlaceholder.innerHTML = '<div class="retold-remote-vex-frame-loading">Failed: ' + tmpSelf._escapeHTML(pError.message) + '</div>'
+					tmpPlaceholder.innerHTML = '<div class="retold-remote-vex-frame-loading">Failed: ' + tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pError.message) + '</div>'
 						+ '<div class="retold-remote-vex-frame-info">'
-						+ '<span class="retold-remote-vex-frame-timestamp">' + tmpSelf._formatTimestamp(tmpTimestamp) + '</span>'
+						+ '<span class="retold-remote-vex-frame-timestamp">' + tmpSelf.pict.providers['RetoldRemote-FormattingUtilities'].formatTimestamp(tmpTimestamp) + '</span>'
 						+ '<span class="retold-remote-vex-frame-index">error</span>'
 						+ '</div>';
 				}
@@ -780,7 +780,7 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		tmpEl.id = pPlaceholderId;
 		tmpEl.innerHTML = '<div class="retold-remote-vex-frame-loading">Extracting...</div>'
 			+ '<div class="retold-remote-vex-frame-info">'
-			+ '<span class="retold-remote-vex-frame-timestamp">' + this._formatTimestamp(pTimestamp) + '</span>'
+			+ '<span class="retold-remote-vex-frame-timestamp">' + this.pict.providers['RetoldRemote-FormattingUtilities'].formatTimestamp(pTimestamp) + '</span>'
 			+ '<span class="retold-remote-vex-frame-index">custom</span>'
 			+ '</div>';
 
@@ -840,25 +840,6 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		return parseFloat(pText) || 0;
 	}
 
-	/**
-	 * Format a timestamp in seconds to a human-readable string.
-	 *
-	 * @param {number} pSeconds - Timestamp in seconds
-	 * @returns {string} Formatted string like "1:23" or "1:02:34"
-	 */
-	_formatTimestamp(pSeconds)
-	{
-		let tmpHours = Math.floor(pSeconds / 3600);
-		let tmpMinutes = Math.floor((pSeconds % 3600) / 60);
-		let tmpSecs = Math.floor(pSeconds % 60);
-
-		if (tmpHours > 0)
-		{
-			return tmpHours + ':' + String(tmpMinutes).padStart(2, '0') + ':' + String(tmpSecs).padStart(2, '0');
-		}
-		return tmpMinutes + ':' + String(tmpSecs).padStart(2, '0');
-	}
-
 	/**
 	 * Open a frame at full size in an inline preview overlay.
 	 *
@@ -1000,11 +981,11 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		tmpHTML += '<div class="retold-remote-vex-preview-header">';
 		tmpHTML += '<button class="retold-remote-vex-nav-btn" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].closeFramePreview()" title="Back (Esc)">&larr; Back</button>';
 		tmpHTML += '<button class="retold-remote-vex-nav-btn" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].previewPrevFrame()" title="Previous (\u2190)">&lsaquo; Prev</button>';
-		tmpHTML += '<div class="retold-remote-vex-preview-title" id="RetoldRemote-VEX-PreviewTitle">' + this._escapeHTML(pLabel) + '</div>';
+		tmpHTML += '<div class="retold-remote-vex-preview-title" id="RetoldRemote-VEX-PreviewTitle">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pLabel) + '</div>';
 		tmpHTML += '<button class="retold-remote-vex-nav-btn" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].previewNextFrame()" title="Next (\u2192)">Next &rsaquo;</button>';
 		tmpHTML += '</div>';
 		tmpHTML += '<div class="retold-remote-vex-preview-body" id="RetoldRemote-VEX-PreviewBody">';
-		tmpHTML += '<img src="' + pURL + '" alt="' + this._escapeHTML(pLabel) + '">';
+		tmpHTML += '<img src="' + pURL + '" alt="' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pLabel) + '">';
 		tmpHTML += '</div>';
 
 		tmpBackdrop.innerHTML = tmpHTML;
@@ -1099,7 +1080,7 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		let tmpBody = document.getElementById('RetoldRemote-VEX-PreviewBody');
 		if (tmpBody)
 		{
-			tmpBody.innerHTML = '<img src="' + tmpURL + '" alt="' + this._escapeHTML(tmpFrame.Label) + '">';
+			tmpBody.innerHTML = '<img src="' + tmpURL + '" alt="' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(tmpFrame.Label) + '">';
 		}
 
 		let tmpTitle = document.getElementById('RetoldRemote-VEX-PreviewTitle');
@@ -1201,27 +1182,12 @@ class RetoldRemoteVideoExplorerView extends libPictView
 		if (tmpBody)
 		{
 			tmpBody.innerHTML = '<div class="retold-remote-vex-error">'
-				+ '<div class="retold-remote-vex-error-message">' + this._escapeHTML(pMessage || 'An error occurred.') + '</div>'
+				+ '<div class="retold-remote-vex-error-message">' + this.pict.providers['RetoldRemote-FormattingUtilities'].escapeHTML(pMessage || 'An error occurred.') + '</div>'
 				+ '<button class="retold-remote-vex-nav-btn" onclick="pict.views[\'RetoldRemote-VideoExplorer\'].goBack()">Back to Video</button>'
 				+ '</div>';
 		}
 	}
 
-	_escapeHTML(pText)
-	{
-		if (!pText) return '';
-		return pText.replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
-	}
-
-	_formatFileSize(pBytes)
-	{
-		if (!pBytes || pBytes === 0) return '0 B';
-		let tmpUnits = ['B', 'KB', 'MB', 'GB', 'TB'];
-		let tmpIndex = Math.floor(Math.log(pBytes) / Math.log(1024));
-		if (tmpIndex >= tmpUnits.length) tmpIndex = tmpUnits.length - 1;
-		let tmpSize = pBytes / Math.pow(1024, tmpIndex);
-		return tmpSize.toFixed(tmpIndex === 0 ? 0 : 1) + ' ' + tmpUnits[tmpIndex];
-	}
 }
 
 RetoldRemoteVideoExplorerView.default_configuration = _ViewConfiguration;

package/web-application/css/docuserve.css

@@ -0,0 +1,73 @@
+/* ============================================================================
+   Pict Docuserve - Base Styles
+   ============================================================================ */
+
+/* Reset and base */
+*, *::before, *::after {
+	box-sizing: border-box;
+}
+
+html, body {
+	margin: 0;
+	padding: 0;
+	font-family: -apple-system, BlinkMacSystemFont, "Segoe UI", Roboto, "Helvetica Neue", Arial, sans-serif;
+	font-size: 16px;
+	line-height: 1.5;
+	color: #423D37;
+	background-color: #fff;
+	-webkit-font-smoothing: antialiased;
+	-moz-osx-font-smoothing: grayscale;
+}
+
+/* Typography */
+h1, h2, h3, h4, h5, h6 {
+	margin-top: 0;
+	line-height: 1.3;
+}
+
+a {
+	color: #2E7D74;
+	text-decoration: none;
+}
+
+a:hover {
+	color: #256861;
+}
+
+/* Application container */
+#Docuserve-Application-Container {
+	min-height: 100vh;
+}
+
+/* Utility: scrollbar styling */
+::-webkit-scrollbar {
+	width: 8px;
+}
+
+::-webkit-scrollbar-track {
+	background: #F5F0E8;
+}
+
+::-webkit-scrollbar-thumb {
+	background: #D4CCBE;
+	border-radius: 4px;
+}
+
+::-webkit-scrollbar-thumb:hover {
+	background: #B5AA9A;
+}
+
+/* Responsive adjustments */
+@media (max-width: 768px) {
+	html {
+		font-size: 14px;
+	}
+
+	#Docuserve-Sidebar-Container {
+		display: none;
+	}
+
+	.docuserve-body {
+		flex-direction: column;
+	}
+}

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

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

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.