JetKVM Advanced, CGO-based 2-way Audio Support

.devcontainer/install_audio_deps.sh

@@ -0,0 +1,88 @@
+#!/bin/bash
+# .devcontainer/install_audio_deps.sh
+# Build ALSA and Opus static libs for ARM in /opt/jetkvm-audio-libs
+set -e
+
+# Sudo wrapper function
+function use_sudo() {
+  if [ "$UID" -eq 0 ] || [ -z "$(which sudo 2>/dev/null)" ]; then
+    "$@"
+  else
+    sudo -E "$@"
+  fi
+}
+
+# Accept version parameters or use defaults
+ALSA_VERSION="${1:-1.2.14}"
+OPUS_VERSION="${2:-1.5.2}"
+SPEEXDSP_VERSION="${3:-1.2.1}"
+
+AUDIO_LIBS_DIR="/opt/jetkvm-audio-libs"
+BUILDKIT_PATH="/opt/jetkvm-native-buildkit"
+BUILDKIT_FLAVOR="arm-rockchip830-linux-uclibcgnueabihf"
+CROSS_PREFIX="$BUILDKIT_PATH/bin/$BUILDKIT_FLAVOR"
+
+# Create directory with proper permissions
+use_sudo mkdir -p "$AUDIO_LIBS_DIR"
+use_sudo chmod 777 "$AUDIO_LIBS_DIR"
+cd "$AUDIO_LIBS_DIR"
+
+# Download sources
+[ -f alsa-lib-${ALSA_VERSION}.tar.bz2 ] || wget -N https://www.alsa-project.org/files/pub/lib/alsa-lib-${ALSA_VERSION}.tar.bz2
+[ -f opus-${OPUS_VERSION}.tar.gz ] || wget -N https://downloads.xiph.org/releases/opus/opus-${OPUS_VERSION}.tar.gz
+[ -f speexdsp-${SPEEXDSP_VERSION}.tar.gz ] || wget -N https://ftp.osuosl.org/pub/xiph/releases/speex/speexdsp-${SPEEXDSP_VERSION}.tar.gz
+
+# Extract
+[ -d alsa-lib-${ALSA_VERSION} ] || tar xf alsa-lib-${ALSA_VERSION}.tar.bz2
+[ -d opus-${OPUS_VERSION} ] || tar xf opus-${OPUS_VERSION}.tar.gz
+[ -d speexdsp-${SPEEXDSP_VERSION} ] || tar xf speexdsp-${SPEEXDSP_VERSION}.tar.gz
+
+# ARM Cortex-A7 optimization flags with NEON support
+OPTIM_CFLAGS="-O2 -mfpu=neon -mtune=cortex-a7 -mfloat-abi=hard -DNDEBUG"
+
+export CC="${CROSS_PREFIX}-gcc"
+export CFLAGS="$OPTIM_CFLAGS"
+export CXXFLAGS="$OPTIM_CFLAGS"
+
+# Build ALSA
+cd alsa-lib-${ALSA_VERSION}
+if [ ! -f .built ]; then
+  chown -R $(whoami):$(whoami) .
+  # Minimal ALSA configuration for direct hw: device access with SpeexDSP resampling
+  CFLAGS="$OPTIM_CFLAGS" ./configure --host $BUILDKIT_FLAVOR \
+    --enable-static=yes --enable-shared=no \
+    --with-pcm-plugins=linear,copy \
+    --disable-seq --disable-rawmidi --disable-ucm \
+    --disable-python --disable-old-symbols \
+    --disable-topology --disable-hwdep --disable-mixer \
+    --disable-alisp --disable-aload --disable-resmgr
+  make -j$(nproc)
+  touch .built
+fi
+cd ..
+
+# Build Opus
+cd opus-${OPUS_VERSION}
+if [ ! -f .built ]; then
+  chown -R $(whoami):$(whoami) .
+  CFLAGS="$OPTIM_CFLAGS" ./configure --host $BUILDKIT_FLAVOR --enable-static=yes --enable-shared=no --enable-fixed-point
+  make -j$(nproc)
+  touch .built
+fi
+cd ..
+
+# Build SpeexDSP
+cd speexdsp-${SPEEXDSP_VERSION}
+if [ ! -f .built ]; then
+  chown -R $(whoami):$(whoami) .
+  # NEON-optimized high-quality resampler
+  CFLAGS="$OPTIM_CFLAGS" ./configure --host $BUILDKIT_FLAVOR \
+    --enable-static=yes --enable-shared=no \
+    --enable-neon \
+    --disable-examples
+  make -j$(nproc)
+  touch .built
+fi
+cd ..
+
+echo "ALSA, Opus, and SpeexDSP built in $AUDIO_LIBS_DIR"

.github/copilot-instructions.md

@@ -0,0 +1,115 @@
+# JetKVM Copilot Instructions
+
+## Architecture Overview
+
+JetKVM is a high-performance KVM-over-IP solution with **bidirectional architecture**: a Go backend running on ARM hardware and a React/TypeScript frontend served by the device. The system provides real-time video streaming, HID input, virtual media mounting, and **2-way audio support** via WebRTC.
+
+### Core Components
+
+- **Backend**: Go application (`main.go`, `web.go`, `webrtc.go`) handling WebRTC, HTTP APIs, hardware interfaces
+- **Frontend**: React/TypeScript SPA (`ui/src/`) with Vite build system, served as embedded static files
+- **Hardware Layer**: CGO bridge (`internal/native/`) to ARM SoC for video capture, USB gadget, display control
+- **Audio System**: In-process CGO implementation (`internal/audio/`) with ALSA/Opus for USB Audio Gadget streaming
+- **USB Gadget**: Configurable emulation (`internal/usbgadget/`) - keyboard, mouse, mass storage, **audio device**
+
+## Development Workflows
+
+### Quick Development Commands
+```bash
+# Full development deployment (most common)
+./dev_deploy.sh -r <DEVICE_IP>
+
+# UI-only changes (faster iteration)
+cd ui && ./dev_device.sh <DEVICE_IP>
+
+# Backend-only changes (skip UI build)
+./dev_deploy.sh -r <DEVICE_IP> --skip-ui-build
+
+# Build for release
+make build_release
+```
+
+### Critical Build Dependencies
+- **Audio libraries**: `make build_audio_deps` builds ALSA and Opus static libs for ARM
+- **Native CGO**: `make build_native` compiles hardware interface layer
+- **Cross-compilation**: ARM7 with buildkit toolchain at `/opt/jetkvm-native-buildkit`
+
+### Testing
+```bash
+# Run Go tests on device
+./dev_deploy.sh -r <DEVICE_IP> --run-go-tests
+
+# UI linting
+cd ui && npm run lint
+```
+
+## Project-Specific Patterns
+
+### Configuration Management
+- **Single config file**: `/userdata/kvm_config.json` persisted across updates
+- **Config struct**: `config.go` with JSON tags, atomic operations for thread safety
+- **Migration pattern**: Use `ensureConfigLoaded()` before config access
+
+### WebRTC Architecture
+- **Session management**: `webrtc.go` handles peer connections with connection pooling
+- **Media tracks**: Separate video and **stereo audio tracks** in independent MediaStreams
+- **Data channels**: RPC (ordered), HID (unordered), upload, terminal, serial channels
+- **SDP munging**: Frontend modifies SDP for Opus stereo parameters (`OPUS_STEREO_PARAMS`)
+
+### Audio Implementation Details
+- **USB Audio Gadget**: UAC1 device presenting as stereo speakers + microphone
+- **Bidirectional streaming**: Output (device→browser) and input (browser→device) 
+- **CGO integration**: `internal/audio/cgo_source.go` bridges Go↔C for ALSA operations
+- **Frame-based processing**: 20ms Opus frames (960 samples @ 48kHz) for low latency
+
+### Frontend State Management
+- **Zustand stores**: `hooks/stores.ts` - RTC, UI, Settings, Video state with persistence
+- **JSON-RPC communication**: `useJsonRpc` hook for backend API calls
+- **Localization**: Paraglide.js with compile-time validation - all UI strings use `m.key()` pattern
+
+### USB Gadget Configuration
+- **Configfs-based**: Dynamic reconfiguration via `/sys/kernel/config/usb_gadget/`
+- **Transaction pattern**: `WithTransaction()` ensures atomic gadget changes
+- **Device composition**: Keyboard + mouse + mass storage + **audio** with individual toggle support
+
+## Integration Patterns
+
+### Backend API Structure
+- **JSON-RPC over WebSocket**: Primary communication via data channels
+- **HTTP endpoints**: `/api/*` for REST operations, `/static/*` for UI assets
+- **Configuration endpoints**: `rpc*` functions in `jsonrpc.go` with parameter validation
+
+### Cross-Component Communication
+- **Video pipeline**: `native.go` → WebRTC track → browser via H.264 streaming
+- **HID input**: Browser → WebRTC data channel → `internal/usbgadget/hid_*.go` → Linux gadget
+- **Audio pipeline**: ALSA capture → Opus encode → WebRTC → browser speakers (and reverse for mic)
+- **Virtual media**: HTTP upload → storage → NBD server → USB mass storage gadget
+
+### Error Handling Patterns
+- **Graceful degradation**: Audio/video failures don't crash core functionality
+- **Session isolation**: Per-connection logging with `connectionID` context
+- **Recovery mechanisms**: USB gadget timeouts, audio restart on device changes
+
+## Key Files for Common Tasks
+
+### Adding new RPC endpoints
+1. Add handler function in `jsonrpc.go` 
+2. Register in `rpcHandlers` map
+3. Add frontend hook in `useJsonRpc`
+
+### USB device modifications
+- `internal/usbgadget/config.go` - gadget composition and attributes
+- `internal/usbgadget/hid_*.go` - HID device implementations
+
+### Audio feature development
+- `audio.go` - high-level audio management and session integration
+- `internal/audio/` - CGO sources, relays, and C audio processing
+
+### Frontend feature development
+- `ui/src/routes/` - page components
+- `ui/src/components/` - reusable UI components  
+- `ui/localization/messages/en.json` - localizable strings
+
+---
+
+*This codebase uses advanced patterns like CGO, USB gadgets, and real-time media streaming. Focus on understanding the session lifecycle and cross-compilation requirements for effective development.*

.gitignore

@@ -14,4 +14,14 @@ node_modules
 #internal/native/include
 #internal/native/lib
 
-ui/reports
+ui/reports
+
+# Log files
+*.log
+app.log
+deploy.log
+
+# Development files
+.devcontainer.json
+utilities/
+core

DEVELOPMENT.md

@@ -31,6 +31,21 @@ If you're using Windows, we strongly recommend using **WSL (Windows Subsystem fo
 
 This ensures compatibility with shell scripts and build tools used in the project.
 
+#### Using DevPod
+
+**For Apple Silicon (M1/M2/M3/M4) Mac users:** You must set the Docker platform to `linux/amd64` before starting the DevPod container, as the JetKVM build system requires x86_64 architecture:
+
+```bash
+export DOCKER_DEFAULT_PLATFORM=linux/amd64
+devpod up . --id kvm --provider docker --devcontainer-path .devcontainer/docker/devcontainer.json
+```
+
+After the container starts, you'll need to manually install build dependencies:
+
+```bash
+bash .devcontainer/install-deps.sh
+```
+
 ### Project Setup
 
 1. **Clone the repository:**

Dockerfile.build

@@ -6,6 +6,8 @@ ENV GOPATH=/go
 ENV PATH=$GOPATH/bin:/usr/local/go/bin:$PATH
 
 COPY install-deps.sh /install-deps.sh
+COPY install_audio_deps.sh /install_audio_deps.sh
+
 RUN /install-deps.sh
 
 # Create build directory
@@ -21,4 +23,4 @@ RUN go mod download && go mod verify
 COPY entrypoint.sh /entrypoint.sh
 RUN chmod +x /entrypoint.sh
 
-ENTRYPOINT [ "/entrypoint.sh" ]
+ENTRYPOINT [ "/entrypoint.sh" ]

Makefile

@@ -47,6 +47,10 @@ BIN_DIR := $(shell pwd)/bin
 
 TEST_DIRS := $(shell find . -name "*_test.go" -type f -exec dirname {} \; | sort -u)
 
+# Build ALSA and Opus static libs for ARM in /opt/jetkvm-audio-libs
+build_audio_deps:
+	bash .devcontainer/install_audio_deps.sh
+
 build_native:
 	@if [ "$(SKIP_NATIVE_IF_EXISTS)" = "1" ] && [ -f "internal/native/cgo/lib/libjknative.a" ]; then \
 		echo "libjknative.a already exists, skipping native build..."; \
@@ -136,4 +140,32 @@ release:
 	@echo "Uploading release..."
 	@shasum -a 256 bin/jetkvm_app | cut -d ' ' -f 1 > bin/jetkvm_app.sha256
 	rclone copyto bin/jetkvm_app r2://jetkvm-update/app/$(VERSION)/jetkvm_app
-	rclone copyto bin/jetkvm_app.sha256 r2://jetkvm-update/app/$(VERSION)/jetkvm_app.sha256
+	rclone copyto bin/jetkvm_app.sha256 r2://jetkvm-update/app/$(VERSION)/jetkvm_app.sha256
+# Run golangci-lint locally with the same configuration as CI
+lint-go: build_audio_deps
+	@echo "Running golangci-lint..."
+	@mkdir -p static && touch static/.gitkeep
+	golangci-lint run --verbose
+
+# Run both Go and UI linting with auto-fix
+lint-fix: lint-go-fix lint-ui-fix
+	@echo "All linting with auto-fix completed successfully!"
+
+# Run golangci-lint with auto-fix
+lint-go-fix: build_audio_deps
+	@echo "Running golangci-lint with auto-fix..."
+	@mkdir -p static && touch static/.gitkeep
+	golangci-lint run --fix --verbose
+
+# Run UI linting locally (mirrors GitHub workflow ui-lint.yml)
+lint-ui:
+	@echo "Running UI lint..."
+	@cd ui && npm ci && npm run lint
+
+# Run UI linting with auto-fix
+lint-ui-fix:
+	@echo "Running UI lint with auto-fix..."
+	@cd ui && npm ci && npm run lint:fix
+
+# Legacy alias for UI linting (for backward compatibility)
+ui-lint: lint-ui