@marineyachtradar/signalk-playback-plugin 0.1.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2025 MarineYachtRadar
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,150 @@
+# MaYaRa Radar Playback Plugin for SignalK
+
+A SignalK plugin for playing back `.mrr` radar recordings through the SignalK Radar API.
+
+## What This Plugin Does
+
+This plugin allows you to play pre-recorded radar data (`.mrr` files) through SignalK's Radar API. During playback, the recording appears as a virtual radar that any SignalK radar consumer can connect to and display.
+
+**Use cases:**
+- Test and develop SignalK radar display applications without live radar hardware
+- Demo radar functionality at exhibitions or presentations
+- Debug radar rendering code with consistent, repeatable data
+- Share interesting radar captures with other developers
+
+## Installation
+
+Install from the **SignalK App Store**:
+
+1. Open your SignalK server web interface
+2. Go to **Appstore** > **Available**
+3. Search for "MaYaRa Radar Playback"
+4. Click **Install**
+5. Restart SignalK when prompted
+
+## Getting Started
+
+### 1. Access the Playback Interface
+
+After installation, navigate to:
+```
+http://your-signalk-server:3000/plugins/@marineyachtradar/signalk-playback-plugin/playback.html
+```
+
+Or find it in SignalK's **Webapps** menu.
+
+### 2. Upload a Recording
+
+You can upload `.mrr` or `.mrr.gz` files:
+- **Drag and drop** a file onto the upload zone
+- Or **click** the upload zone to browse for a file
+
+Recordings are stored on the SignalK server and persist across restarts.
+
+### 3. Load and Play
+
+1. Select a recording from the list
+2. Click **Load** to prepare it for playback
+3. Click **Play** to start playback
+4. Use **Pause** and **Stop** as needed
+5. Enable **Loop** to repeat the recording continuously
+
+### 4. View the Radar
+
+Click **View Radar** to open the radar display. This shows the playback radar using the built-in viewer.
+
+## Viewing with Other Clients
+
+During playback, the recording registers as a virtual radar in SignalK. The radar ID follows the pattern `playback-{filename}`.
+
+### Using mayara-server-signalk-plugin
+
+If you have the **mayara-server-signalk-plugin** installed (the main MaYaRa radar plugin), you can also view playback recordings through its interface:
+
+1. Start playback in this plugin
+2. Open the mayara-server-signalk-plugin's radar viewer
+3. The playback radar will appear in the radar list
+4. Select it to view the recording with full MaYaRa GUI features
+
+### Using Other SignalK Radar Consumers
+
+Any application that implements the SignalK Radar API can display the playback:
+- The radar appears at `/signalk/v2/api/vessels/self/radars/playback-{filename}`
+- Spoke data streams via SignalK's binary WebSocket
+
+## Obtaining Recording Files
+
+Recording files (`.mrr`) are created by **mayara-server** when connected to a live radar:
+
+1. Run mayara-server with a radar connected
+2. Open the recordings page at `http://localhost:6502/recordings.html`
+3. Select a radar and click **Start Recording**
+4. Click **Stop Recording** when done
+5. Download the recording as `.mrr.gz` (compressed)
+6. Upload to this SignalK plugin
+
+## File Format
+
+- `.mrr` - MaYaRa Radar Recording (uncompressed)
+- `.mrr.gz` - Gzip-compressed recording (~95% smaller for transfer)
+
+Both formats are supported for upload. Files are stored uncompressed on the server for fast playback.
+
+## Troubleshooting
+
+**Recording won't load:**
+- Check the SignalK server logs for errors
+- Ensure the file is a valid `.mrr` or `.mrr.gz` file
+- Verify the file wasn't corrupted during transfer
+
+**No radar appears in SignalK:**
+- Make sure playback is started (not just loaded)
+- Refresh the radar consumer application
+- Check that SignalK's Radar API is enabled
+
+**Playback stutters:**
+- This can happen on slower systems with large recordings
+- Try using recordings with fewer spokes per revolution
+
+## Technical Details
+
+This plugin:
+- Reads `.mrr` files directly (no mayara-server required)
+- Registers as a RadarProvider via SignalK's Radar API
+- Emits spoke frames through SignalK's `binaryStreamManager`
+- Plays back frames at their original recorded timing
+- Sets power status to "transmit" so GUI shows radar as active (not STANDBY)
+- Pre-loads all frames for accurate timing
+- Auto-stops current playback when loading a different file
+
+## Development
+
+Build options:
+
+```bash
+# Build with GUI from npm (default)
+node build.js
+
+# Build with local mayara-gui (for development)
+node build.js --local-gui
+
+# Create tarball for manual install (includes public/)
+node build.js --local-gui --pack
+```
+
+The `--local-gui` option copies GUI files from the sibling `../mayara-gui` directory instead of from npm.
+
+The `--pack` option creates a `.tgz` tarball with `public/` included (normally excluded by `.npmignore`). Install with:
+
+```bash
+npm install /path/to/marineyachtradar-signalk-playback-plugin-0.1.0.tgz
+```
+
+## Related Projects
+
+- **[mayara-server](https://github.com/MaYaRa-Marine/mayara-server)** - Standalone radar server (creates recordings)
+- **[mayara-server-signalk-plugin](https://github.com/MaYaRa-Marine/mayara-server-signalk-plugin)** - SignalK plugin for live radar (connects to mayara-server)
+
+## License
+
+MIT License - See [LICENSE](LICENSE) for details.

package/build.js

@@ -0,0 +1,248 @@
+#!/usr/bin/env node
+/**
+ * Build script for mayara-server-signalk-playbackrecordings-plugin
+ *
+ * Copies @marineyachtradar/mayara-gui from npm to public/
+ * The plugin adds its own playback.html for file upload/control.
+ *
+ * Usage: node build.js [options]
+ *   --local-gui  Use local mayara-gui instead of npm (for development)
+ *   --pack       Create a .tgz tarball with public/ included (for manual install)
+ */
+
+const fs = require('fs')
+const path = require('path')
+const { execSync } = require('child_process')
+
+const args = process.argv.slice(2)
+const useLocalGui = args.includes('--local-gui')
+const createPack = args.includes('--pack')
+
+const scriptDir = __dirname
+const publicDest = path.join(scriptDir, 'public')
+
+/**
+ * Recursively copy directory contents
+ */
+function copyDir(src, dest) {
+  if (!fs.existsSync(src)) {
+    console.error(`Source directory not found: ${src}`)
+    process.exit(1)
+  }
+
+  if (fs.existsSync(dest)) {
+    fs.rmSync(dest, { recursive: true })
+  }
+
+  fs.mkdirSync(dest, { recursive: true })
+
+  const entries = fs.readdirSync(src, { withFileTypes: true })
+  for (const entry of entries) {
+    const srcPath = path.join(src, entry.name)
+    const destPath = path.join(dest, entry.name)
+    if (entry.isDirectory()) {
+      copyDir(srcPath, destPath)
+    } else {
+      fs.copyFileSync(srcPath, destPath)
+    }
+  }
+}
+
+/**
+ * Copy GUI from npm package
+ */
+function setupGuiFromNpm() {
+  console.log('Copying GUI from node_modules...\n')
+
+  const guiSource = path.join(scriptDir, 'node_modules', '@marineyachtradar', 'mayara-gui')
+
+  if (!fs.existsSync(guiSource)) {
+    console.error('Error: @marineyachtradar/mayara-gui not found in node_modules')
+    console.error('Make sure it is listed in package.json dependencies')
+    process.exit(1)
+  }
+
+  if (fs.existsSync(publicDest)) {
+    fs.rmSync(publicDest, { recursive: true })
+  }
+  fs.mkdirSync(publicDest, { recursive: true })
+
+  // Copy GUI files (exclude package.json, node_modules, etc.)
+  const guiPatterns = [
+    { ext: '.html' },
+    { ext: '.js' },
+    { ext: '.css' },
+    { ext: '.ico' },
+    { ext: '.svg' },
+    { dir: 'assets' },
+    { dir: 'proto' },
+    { dir: 'protobuf' }
+  ]
+
+  // Exclude recordings.html since we have our own playback UI
+  const excludeFiles = ['recordings.html', 'recordings.js', 'recordings.css']
+
+  const entries = fs.readdirSync(guiSource, { withFileTypes: true })
+  for (const entry of entries) {
+    if (excludeFiles.includes(entry.name)) continue
+
+    const srcPath = path.join(guiSource, entry.name)
+    const destPath = path.join(publicDest, entry.name)
+
+    if (entry.isDirectory()) {
+      if (guiPatterns.some(p => p.dir === entry.name)) {
+        copyDir(srcPath, destPath)
+      }
+    } else {
+      if (guiPatterns.some(p => p.ext && entry.name.endsWith(p.ext))) {
+        fs.copyFileSync(srcPath, destPath)
+      }
+    }
+  }
+
+  // Copy our custom files from plugin/public/ (overrides GUI files)
+  const pluginPublic = path.join(scriptDir, 'plugin', 'public')
+  if (fs.existsSync(pluginPublic)) {
+    const customEntries = fs.readdirSync(pluginPublic, { withFileTypes: true })
+    let customCount = 0
+    for (const entry of customEntries) {
+      const srcPath = path.join(pluginPublic, entry.name)
+      const destPath = path.join(publicDest, entry.name)
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath)
+        customCount++
+      } else {
+        fs.copyFileSync(srcPath, destPath)
+        customCount++
+      }
+    }
+    console.log(`Added ${customCount} custom files from plugin/public/`)
+  }
+
+  const fileCount = fs.readdirSync(publicDest, { recursive: true }).length
+  console.log(`Copied ${fileCount} GUI files to public/\n`)
+}
+
+/**
+ * Copy GUI from local sibling directory (for development)
+ */
+function setupGuiFromLocal() {
+  const localGuiPath = path.join(scriptDir, '..', 'mayara-gui')
+  console.log(`Copying GUI from local ${localGuiPath}...\n`)
+
+  if (fs.existsSync(publicDest)) {
+    fs.rmSync(publicDest, { recursive: true })
+  }
+  fs.mkdirSync(publicDest, { recursive: true })
+
+  const guiPatterns = [
+    { ext: '.html' },
+    { ext: '.js' },
+    { ext: '.css' },
+    { ext: '.ico' },
+    { ext: '.svg' },
+    { dir: 'assets' },
+    { dir: 'proto' },
+    { dir: 'protobuf' }
+  ]
+
+  // Exclude recordings files since we have our own playback UI
+  const excludeFiles = ['recordings.html', 'recordings.js', 'recordings.css']
+
+  const entries = fs.readdirSync(localGuiPath, { withFileTypes: true })
+  for (const entry of entries) {
+    if (excludeFiles.includes(entry.name)) continue
+
+    const srcPath = path.join(localGuiPath, entry.name)
+    const destPath = path.join(publicDest, entry.name)
+
+    if (entry.isDirectory()) {
+      if (guiPatterns.some(p => p.dir === entry.name)) {
+        copyDir(srcPath, destPath)
+      }
+    } else {
+      if (guiPatterns.some(p => p.ext && entry.name.endsWith(p.ext))) {
+        fs.copyFileSync(srcPath, destPath)
+      }
+    }
+  }
+
+  // Copy our custom files from plugin/public/ (overrides GUI files)
+  const pluginPublic = path.join(scriptDir, 'plugin', 'public')
+  if (fs.existsSync(pluginPublic)) {
+    const customEntries = fs.readdirSync(pluginPublic, { withFileTypes: true })
+    let customCount = 0
+    for (const entry of customEntries) {
+      const srcPath = path.join(pluginPublic, entry.name)
+      const destPath = path.join(publicDest, entry.name)
+      if (entry.isDirectory()) {
+        copyDir(srcPath, destPath)
+        customCount++
+      } else {
+        fs.copyFileSync(srcPath, destPath)
+        customCount++
+      }
+    }
+    console.log(`Added ${customCount} custom files from plugin/public/`)
+  }
+
+  const fileCount = fs.readdirSync(publicDest, { recursive: true }).length
+  console.log(`Copied ${fileCount} files from local mayara-gui/ to public/\n`)
+}
+
+function main() {
+  console.log('=== MaYaRa SignalK Playback Plugin Build ===\n')
+
+  // Skip build if public/ already exists with content (installed from --pack tarball)
+  // This prevents postinstall from failing when mayara-gui isn't in node_modules
+  if (fs.existsSync(publicDest) && !useLocalGui && !createPack) {
+    const files = fs.readdirSync(publicDest)
+    if (files.length > 0) {
+      console.log(`public/ already exists with ${files.length} files (installed from tarball)`)
+      console.log('Skipping build.\n')
+      console.log('=== Build complete ===')
+      return
+    }
+  }
+
+  if (useLocalGui) {
+    setupGuiFromLocal()
+  } else {
+    setupGuiFromNpm()
+  }
+
+  // Create tarball if --pack flag is set
+  if (createPack) {
+    console.log('Creating tarball with public/ included...\n')
+
+    // Temporarily remove public/ from .npmignore
+    const npmignorePath = path.join(scriptDir, '.npmignore')
+    const npmignoreContent = fs.readFileSync(npmignorePath, 'utf8')
+    const npmignoreWithoutPublic = npmignoreContent.replace(/^public\/\n?/m, '')
+    fs.writeFileSync(npmignorePath, npmignoreWithoutPublic)
+
+    // Also temporarily add public/ to files in package.json
+    const pkgPath = path.join(scriptDir, 'package.json')
+    const pkgContent = fs.readFileSync(pkgPath, 'utf8')
+    const pkg = JSON.parse(pkgContent)
+    const originalFiles = [...pkg.files]
+    pkg.files.push('public/**/*')
+    fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+
+    try {
+      // Run npm pack
+      execSync('npm pack', { stdio: 'inherit', cwd: scriptDir })
+      console.log('\nTarball created successfully!')
+    } finally {
+      // Restore .npmignore
+      fs.writeFileSync(npmignorePath, npmignoreContent)
+      // Restore package.json
+      pkg.files = originalFiles
+      fs.writeFileSync(pkgPath, JSON.stringify(pkg, null, 2) + '\n')
+    }
+  }
+
+  console.log('\n=== Build complete ===')
+}
+
+main()

package/package.json

@@ -0,0 +1,46 @@
+{
+  "name": "@marineyachtradar/signalk-playback-plugin",
+  "version": "0.1.0",
+  "description": "MaYaRa Radar Playback - Play .mrr radar recordings through SignalK Radar API (Developer Tool)",
+  "main": "plugin/index.js",
+  "scripts": {
+    "build": "node build.js",
+    "postinstall": "node build.js",
+    "test": "echo \"No tests yet\" && exit 0"
+  },
+  "keywords": [
+    "signalk-node-server-plugin",
+    "signalk-webapp",
+    "signalk-category-instruments",
+    "radar",
+    "marine",
+    "mayara",
+    "playback",
+    "recording"
+  ],
+  "signalk": {
+    "displayName": "MaYaRa Radar Playback",
+    "appIcon": "assets/MaYaRa_RED.png",
+    "webapp": {
+      "name": "MaYaRa Radar Playback",
+      "description": "Play .mrr radar recordings for testing SignalK Radar API consumers",
+      "location": "/plugins/@marineyachtradar/signalk-playback-plugin/"
+    }
+  },
+  "files": [
+    "plugin/**/*",
+    "build.js"
+  ],
+  "engines": {
+    "signalk": ">=2.0.0"
+  },
+  "dependencies": {
+    "@marineyachtradar/mayara-gui": "^0.6.0"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/MarineYachtRadar/mayara-server-signalk-playbackrecordings-plugin"
+  },
+  "author": "MarineYachtRadar Contributors",
+  "license": "Apache-2.0"
+}