A derivative of the Cockos NINJAM server (GPL v2, Justin Frankel / Cockos) that adds real-time video channel support alongside audio, plus a thread-per-group architecture for private rooms.
It powers the public NinjamZap rooms (video.ninjamzap.com:2049, :2050) used by the NinjamZap mobile client, and any standard NINJAM client (Reaper/ReaNINJAM, Jamtaba, etc.) can connect for the audio path.
License: GPL v2 — same as upstream NINJAM. See LICENSE and NOTICE.md for the file-by-file lineage of what came from upstream vs what was added in this fork.
Video frames are relayed in-band through the same interval-based protocol that NINJAM already uses for audio. No separate signaling channel; video is just another channel type identified by its fourcc:
H264— H.264 / AVCVP8— VP8 / WebMMJPG— Motion JPEG
The server prioritises audio: each main loop iteration relays audio first and then video, and video frames are dropped first for slow subscribers so that audio quality stays clean even on a congested link.
Tunables (in the server .cfg):
| Directive | Purpose |
|---|---|
AllowVideoChannels yes |
Enable video relay |
VideoTransferTimeout |
Max ms to spend pushing a video frame to one subscriber |
VideoCongestionThreshold |
Send-queue size at which the server starts dropping video frames |
SendBufferKB / RecvBufferKB |
Per-connection socket buffer sizes |
Full protocol/architecture details: docs/VIDEO_SUPPORT.md.
Private rooms (when configured) each run on their own pthread; the public lobby stays on the main thread. Users are migrated between rooms through a mutex-protected queue. When PrivateGroupMode is not configured the server behaves exactly like upstream — no extra threads are created, so there is no overhead for plain public-server use.
cd ninjam/server
make # Linux
MAC=1 make # macOS
./ninjamsrv ../../configs/default.cfgThe binary is ninjam/server/ninjamsrv. It accepts the same CLI flags as upstream:
./ninjamsrv config.cfg [-port 2049] [-logfile server.log] [-pidfile server.pid]SIGHUP reloads the config without restarting; SIGINT shuts down cleanly (joins all room threads).
The included Dockerfile builds the server in a Debian-slim multi-stage image (~23 MB final). It runs two server instances out of the box (ports 2049 and 2050) via configs/entrypoint.sh — handy if you want a single VM to host two rooms.
# Build
docker build -t ninjamzap-server .
# Run (publish both ports)
docker run --rm \
-p 2049:2049 \
-p 2050:2050 \
--name ninjamzap-server \
ninjamzap-serverOverride the configs by bind-mounting your own:
docker run --rm \
-p 2049:2049 -p 2050:2050 \
-v "$PWD/my-2049.cfg:/opt/ninjam/server.cfg:ro" \
-v "$PWD/my-2050.cfg:/opt/ninjam/server-2050.cfg:ro" \
-v "$PWD/motd.txt:/opt/ninjam/motd.txt:ro" \
ninjamzap-serverIf you only need a single port, point the entrypoint at one config or simplify it — the binary itself is just ninjamsrv server.cfg.
Port 2049
MaxUsers 6
MaxChannels 32 2
ServerLicense cclicense.txt
StatusUserPass <user> <pass>
AnonymousUsers yes
AnonymousUsersCanChat yes
AnonymousMaskIP yes
AllowVideoChannels yes
SendBufferKB 2048
RecvBufferKB 1024
ACL 0.0.0.0/0 allow
DefaultTopic "Welcome to your NINJAM room"
DefaultBPM 120
DefaultBPI 16
MOTDFile /opt/ninjam/motd.txt
Annotated reference with every option: ninjam/server/example.cfg.
fly.toml and Dockerfile are tuned for Fly.io. The image is small enough to run on a shared-cpu-1x 256 MB machine.
flyctl auth login
flyctl launch --copy-config --no-deploy # first time only
flyctl deploy
flyctl logs --app <your-app>A few things worth knowing if you go this route:
- Dedicated IPv4 is required. NINJAM is plain TCP, and Fly's shared IPv4 only handles HTTP. Run
flyctl ips allocate-v4(~$2/mo). - No HTTP health checks. The NINJAM server treats Fly's TCP probes as failed client connections — don't configure them.
- Logs. The Dockerfile uses
stdbuf -oLsoflyctl logscaptures output line by line. - Two ports on one machine. Add a second
[[services]]block infly.tomlfor the second port (the IPv4 covers both). The includedentrypoint.shalready supervises twoninjamsrvprocesses.
A working fly.toml template is in this repo.
The bundled entrypoint.sh also runs a third instance on port 2090 configured for invite-only access (AnonymousUsers no). The config is generated at container startup from configs/private-2090.cfg.example with credentials pulled from Fly secrets, so the public repo never carries a real password.
flyctl secrets set \
PRIVATE_ADMIN_USER=jacinside \
PRIVATE_ADMIN_PASS='use-a-long-random-passphrase' \
ROOM_INVITE_PASS='another-long-random-passphrase' \
-a ninjamzap-server
flyctl deployThe generated private-2090.cfg lives only inside the running container (the path is configs/private-*.cfg, gitignored). To rotate any password, update the secret and redeploy.
This fork adds a new cfg directive — RoomPassword <password> [flags] — that powers the invite-link flow without forcing the operator to provision a User entry per invitee. When set, any client that supplies their own nickname + this password is authenticated and granted the listed privileges (default: chat + vote).
RoomPassword s3cr3t-abc-xyz CVThe handshake hashes SHA1(nickname + ":" + room_password) — same construction as a per-user login, so the secret never crosses the wire in cleartext. Explicit User entries take precedence, so admins keep their elevated privileges even if their nickname is the same as a guest's.
This is what makes invite links like https://ninjamzap.com/invite/<token> self-contained: the redeem endpoint hands back { host, port, password } and the app prompts the user only for their preferred nickname.
PRIV_HIDDEN (H) is intentionally rejected at config-parse time — a shared password granting hidden-user status would defeat the user-list utility for everyone in the room.
Port allocation convention:
2049–2079— public servers2080+— private / invite-only
From the NinjamZap mobile client (iOS/Android) or any standard NINJAM client:
- Host:
your.host.example - Port:
2049 - Username: anything (anonymous unless you configure
UserPass)
Topic and welcome message are set via DefaultTopic and MOTDFile.
ninjam/server/usercon.{h,cpp} # user/group state, relay, video drop, threading
ninjam/server/ninjamsrv.cpp # main loop, config parsing, thread lifecycle
ninjam/netmsg.h # Net_Message, Net_Connection, send queue
ninjam/server/Makefile # build (links pthread)
ninjam/server/example.cfg # documented config template
configs/ # production configs + Docker entrypoint
docs/ # protocol & architecture notes
WDL/ # Cockos WDL helper library (vendored)
Issues and PRs welcome. If you're using this in production we'd love to know — open an issue or reach out via support@ninjamzap.com.
Built on top of the original Cockos NINJAM by Justin Frankel & Brennan Underwood. NINJAM is the reason any of this works at all.