storm/skald
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Add Skald hard fork plan

Browse Source
This commit is contained in:
Storm Dragon
2026-05-17 22:08:19 -04:00
parent f718385342
commit 77edf0539c
1 changed files with 238 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files
todo.txt
+238
View File
@@ -0,0 +1,238 @@
# Skald Hard Fork - Master TODO
#
# Goal:
# Turn this Galene-derived repository into Skald: a new, audio-only,
# hall-based conferencing server. This is a hard fork, so compatibility with
# Galene names, URLs, video behavior, and recording format is intentionally
# not the default.
#
# Legend:
# - item = needs doing
# + item = implemented, needs testing
# X item = tested and done
#
# Non-negotiable target state:
# - Project name is Skald everywhere.
# - Halls replace groups/rooms everywhere user-facing and in internal code
# where practical.
# - Video is removed, not hidden.
# - Incoming video is rejected.
# - The browser UI is audio-only and accessible.
# - Recordings are single mixed Ogg Opus audio files.
# - No legacy Galene compatibility paths or fallback shims unless explicitly
# added later by choice.
# ============================================================================
# PHASE 0: BASELINE INVENTORY AND GUARDRAILS
# ============================================================================
- Record the current upstream/fork point in CHANGES or a new fork note
- Capture current baseline: `go test ./...` result before behavior changes
- Capture current baseline: `go build ./...` result before behavior changes
- Inventory generated/static assets, including static/example and third-party assets
- Inventory all public URLs: /group/, /public-groups.json, /recordings/, /galene-api/
- Inventory all config/data paths: groups/, data/, recordings/, galenectl.json
- Inventory all Galene binary/service names in docs, scripts, examples, and tests
- Decide whether existing stored data will be migrated manually or treated as incompatible
- Keep the old LICENSE intact and preserve required attribution
# ============================================================================
# PHASE 1: FOUNDATION AND TOTAL REBRANDING
# ============================================================================
- Rename Go module: github.com/jech/galene -> git.stormux.org/storm/skald
- Update all internal Go import paths across source and tests
- Rename galene.go -> skald.go and keep the main package entrypoint working
- Rename galenectl/ directory and binary to skaldctl/
- Rename static/galene.css -> static/skald.css
- Rename static/galene.js -> static/skald.js
- Rename static/galene.html -> static/skald.html
- Update webserver static serving to load skald.html and renamed assets
- Update all HTML, JS, CSS, docs, tests, and examples that reference renamed assets
- Rename galene-*.md docs to skald-*.md
- Replace "Galene", "Galène", and "galene" with "Skald" and "skald" where they refer to this project
- Keep historical upstream references only where they are attribution, changelog history, or license context
- Rename default binary, service, and install examples from galene to skald
- Rename galenectl config file to skaldctl.json
- Update CHANGES with Skald fork point and first Skald development section
- Verify `go test ./...` compiles after the pure project rename pass
- Search for remaining Galene names and classify each survivor as attribution/history or a bug
# ============================================================================
# PHASE 2: HALL TERMINOLOGY AND DATA MODEL
# ============================================================================
- Rename Go package group/ to hall/ if the package-wide rename stays tractable
- Rename package declarations, types, variables, funcs, tests, and comments from group to hall
- Rename Group type to Hall and update all compile errors intentionally
- Rename group description files/concepts to hall description files/concepts
- Rename default directory flag: -groups -> -halls
- Rename default data directory: groups/ -> halls/
- Rename public listing concept from public groups to public halls
- Rename subgroups to subhalls everywhere, including JSON fields and commands
- Rename auto-subgroups -> auto-subhalls
- Rename allow-subgroups -> allow-subhalls
- Rename include-subgroups -> include-subhalls
- Rename group action names to hall action names where exposed to clients
- Rename chat/help commands such as /subgroups to /subhalls
- Update tests to use generic placeholder names, not real usernames
- Verify no user-facing "group", "groups", "room", or "rooms" remain except attribution/history
- Verify old group JSON/config paths are not silently accepted unless explicitly reintroduced later
# ============================================================================
# PHASE 3: URLS, API, PROTOCOL, AND CONTROL TOOL
# ============================================================================
- Rename browser hall URLs from /group/name/ to /hall/name/
- Rename /public-groups.json to /public-halls.json
- Rename /galene-api/ to /skald-api/
- Rename API collection paths from .groups to .halls
- Rename protocol join fields from group to hall
- Rename protocol callbacks/events from joined group semantics to joined hall semantics
- Update static/protocol.js public API: ServerConnection.join and related callbacks
- Update static/management.js to use /skald-api/v0/.halls/
- Update static/mainpage.js to open /hall/ URLs and fetch /public-halls.json
- Update stats endpoint naming only if it exposes Galene/group terminology
- Update skaldctl command names: create-hall, update-hall, delete-hall, list-halls
- Update skaldctl flags: -hall, -include-subhalls, -auto-subhalls, etc.
- Update skaldctl help text and error messages
- Update API and webserver tests for /hall/ and /skald-api/
- Verify old /group/, /public-groups.json, /galene-api/, and .groups paths fail clearly
- Verify protocol backward compatibility with Galene is intentionally broken
# ============================================================================
# PHASE 4: BACKEND - STRIP VIDEO COMPLETELY
# ============================================================================
- Remove video codec constants and helpers from codecs/ package
- Remove or rewrite video-only codec tests
- Strip video/vp8, video/vp9, video/av1, and video/h264 from SDP negotiation
- Ensure audio/opus remains negotiated correctly
- Reject incoming video m-lines/transceivers at WebRTC peer connection setup
- Reject or close incoming video tracks if a browser still sends them
- Ensure rejection is explicit in logs without crashing the hall
- Remove outgoing video track routing from rtpconn/ and hall/
- Remove simulcast and SVC handling
- Remove video bandwidth estimation and video throughput selection
- Remove video-specific RTCP behavior such as PLI/FIR/keyframe requests
- Remove screenshare backend support
- Remove presentation/file-as-video support if it depends on video tracks
- Remove background blur support and background-blur-worker.js from the served app
- Remove video fields from hall descriptions, stats, API responses, and protocol docs
- Check WHIP/WHEP-style endpoints for video assumptions and either make audio-only or remove
- Ensure browsers that request audio+video get a working audio-only session or a clear video rejection
- Verify two browser clients can join one hall and exchange audio only
- Verify a client attempting camera or screenshare cannot publish video
# ============================================================================
# PHASE 5: FRONTEND - AUDIO-ONLY USER EXPERIENCE
# ============================================================================
- Remove all <video> elements and video containers from skald.html
- Remove camera buttons and presentation buttons tied to camera/video behavior
- Remove screenshare button and related menu commands
- Remove video quality, resolution, throughput, simulcast, and collapse controls
- Remove video device selector and camera permission flow
- Remove hideVideo(), showVideo(), getMaxVideoThroughput(), and related JS paths
- Remove background blur UI, worker references, and CSS
- Keep microphone mute/unmute behavior intact
- Keep audio input and output device selection intact
- Keep chat, user list, moderation, locking, recording controls, and status messages
- Rename visible text in skald.html, index.html, stats.html, mainpage.js, management.js, and protocol errors
- Replace public groups UI with public halls UI
- Remove video CSS from skald.css and common.css
- Check layout after removing the video pane; no dead space or hidden required controls
- Preserve keyboard access with Tab and Shift+Tab through all controls
- Ensure controls have labels or accessible names after icon/button cleanup
- Verify audio-only UI loads without 404s for renamed assets
- Verify joining, muting, chat, recording controls, and leaving work from keyboard
# ============================================================================
# PHASE 6: RECORDING REWRITE - SINGLE MIXED OGG OPUS
# ============================================================================
- Remove diskwriter dependency on github.com/at-wat/ebml-go and WebM/Matroska writing
- Remove per-track/per-participant WebM recording logic
- Remove video recording fields such as hasVideo, width, height, keyframes, and video MIME handling
- Decide final mixer implementation before coding:
* Decode all active Opus RTP audio to 48 kHz PCM
* Maintain a per-source jitter/timing buffer so join/leave does not corrupt the mix
* Mix to stereo with clipping prevention or limiting
* Insert silence for missing frames rather than blocking the mixer
* Encode mixed PCM to Ogg Opus
- Evaluate Go-native decode/encode/container libraries versus ffmpeg subprocess
- If using ffmpeg, add a startup check and clear admin/operator error when ffmpeg is missing
- If using ffmpeg, use nonblocking stdin writes and drain stderr safely
- If using ffmpeg, command shape starts from:
ffmpeg -f s16le -ar 48000 -ac 2 -i pipe:0 -c:a libopus -b:a 128k output.ogg
- Ensure recording work cannot block WebRTC packet handling
- Name recording files skald-recording-YYYYMMDD-HHMMSS.ogg
- Avoid usernames or live personal identifiers in recording filenames
- Store one recording file per hall recording session
- Close recordings cleanly on explicit stop
- Close recordings cleanly when the hall empties
- Handle participant join/leave during recording without stopping the file
- Handle mute/unmute during recording without stale audio
- Handle recording start when no one is speaking
- Add focused mixer/recording tests with synthetic audio where possible
- Verify produced Ogg Opus file with `ffprobe` or equivalent
- Verify produced file plays in a standard audio player
# ============================================================================
# PHASE 7: CONFIGURATION, INSTALLATION, AND DEPLOYMENT SURFACES
# ============================================================================
- Update command-line flags and help output for Skald and halls
- Update default examples for halls/, data/, recordings/, and skaldctl.json
- Update systemd service examples to skald user, binary, and paths
- Update reverse proxy examples to /hall/ and /skald-api/
- Update TURN/STUN docs only where project name or URLs changed
- Update Docker/container or packaging files if present later
- Update .gitignore for renamed binaries, config files, and generated artifacts
- Verify there are no stale install commands that build or run galene/galenectl
# ============================================================================
# PHASE 8: DOCUMENTATION
# ============================================================================
- Rewrite README.md to describe Skald as audio-only hall conferencing
- Rewrite skald-install.md for new project name, binary names, and hall paths
- Rewrite skald.md admin/usage docs for audio-only behavior
- Rewrite skald-client.md for audio-only client authors
- Rewrite skald-protocol.md for hall terminology and audio-only tracks
- Rewrite skald-api.md for /skald-api/ and .halls paths
- Remove video, camera, screenshare, simulcast, SVC, and WebM recording instructions
- Add Ogg Opus recording documentation
- Document that incoming video is rejected by design
- Document that Galene protocol/API compatibility is intentionally broken
- Document any required external ffmpeg dependency if the recorder uses ffmpeg
- Check docs for old real-person sample usernames and replace with placeholders
# ============================================================================
# PHASE 9: VERIFICATION AND CLEANUP
# ============================================================================
- Run `go test ./...` and fix failures caused by the fork work
- Run `go vet ./...` and resolve real issues
- Run focused webserver/API tests for /hall/ and /skald-api/
- Run focused protocol/frontend checks if the project has a JS typecheck/test path
- Search source/docs for remaining Galene names
- Search source/docs for remaining /group/, .groups, public-groups, galenectl, and galene-api
- Search source/docs for remaining video, camera, screenshare, simulcast, WebM, and Matroska references
- Search source/docs for remaining group/room terminology in user-facing surfaces
- Classify allowed survivors as attribution/history/third-party icon names only
- Build skald binary
- Build skaldctl binary
- Run a local server and verify static pages load without 404s
- Test: create a hall with skaldctl
- Test: list halls with skaldctl
- Test: join one hall from two browsers and confirm two-way audio
- Test: attempt to publish video and confirm rejection
- Test: start recording and confirm one Ogg Opus file appears
- Test: join a third participant during recording and confirm the mix continues
- Test: mute/unmute during recording and confirm the output reflects it
- Test: leave all participants and confirm recording stops cleanly
- Test: play the recording in a standard audio player
- Test: restart server and verify halls/config load from the new paths
- Remove obsolete files that are no longer served or built
- Do a final diff review for accidental compatibility shims or stale Galene naming