SS - HLM

Multi-camera live production app for macOS, with an iPhone companion app that turns any iPhone into a wireless network camera over the local Wi-Fi.

Built in a Claude-assisted "vibe coding" flow. Architecture is intentional; implementation is rough at the edges. PRs and issues welcome.

---

What's in this repo

Path	What
Sources/	macOS app (SwiftPM, executable target Helm)
Packages/HelmTransport	Shared Swift package — wire protocol + codecs (Mac+iOS)
HelmCamera/	iOS companion app (XcodeGen-driven Xcode project)
Tests/	Mac-side tests
Docs/design/	Original product/UX docs
Docs/	Engineering docs (deep dives, wire spec, status)
scripts/	Build & launch helpers

---

Architecture

              ┌──────────────────────────────────────────────┐
              │                  iPhone                      │
              │  ┌────────────────────────────────────────┐  │
              │  │ HelmCamera.app (HelmCamera/)           │  │
              │  │  AVCapture → H264Encoder → HelmCameraSender ──┐
              │  └────────────────────────────────────────┘  │  │
              └──────────────────────────────────────────────┘  │ TCP
                                                                │ over
                                Bonjour _helm._tcp              │ Wi-Fi
              ┌──────────────────────────────────────────────┐  │
              │                   Mac                        │  │
              │  ┌────────────────────────────────────────┐  │  │
              │  │ Helm.app (Sources/HelmApp + HelmUI)    │  │  │
              │  │   ↑                                    │  │  │
              │  │ MediaPipeline ← HelmCameraReceiver ────┼──┼──┘
              │  │   ↑                                    │  │
              │  │ HelmCameraDirectory ← HelmDirectorListener
              │  └────────────────────────────────────────┘  │
              └──────────────────────────────────────────────┘

HelmTransport is a shared Swift package that both apps import — same Codable types and binary framing on both sides.

---

Quick start (macOS)

Requires: macOS 14+, Xcode 26+ command-line tools.

swift build
./scripts/run-helm.sh

scripts/run-helm.sh is the canonical way to launch — it copies the fresh binary into .build/.../Helm.app/Contents/MacOS/ first because SwiftPM's "Helm.app" bundle isn't auto-updated on every rebuild.

---

Quick start (iPhone)

Requires: free or paid Apple Developer account, iOS 17+ device, Xcode 26+, xcodegen (brew install xcodegen).

./scripts/run-helm-camera.sh

This regenerates HelmCamera/HelmCamera.xcodeproj from project.yml and opens it in Xcode. Then in Xcode:

1. Select the HelmCamera target → Signing & Capabilities → set Team to your Apple ID
2. Plug in iPhone, pick it as the run destination
3. Hit ⌘R

First-time only: the iPhone needs Developer Mode enabled (Settings → Privacy & Security → Developer Mode).

---

Verify everything compiles

./scripts/verify.sh

Runs swift build, swift test (HelmTransport unit tests), xcodegen generate, and xcodebuild for iPhoneSimulator — in parallel where possible.

---

Read next

• CLAUDE.md — orientation for an AI coding agent
• Docs/HELM_CAMERA_FEATURE.md — deep dive on the iPhone-as-camera feature
• Docs/WIRE_PROTOCOL.md — byte-level spec for _helm._tcp
• Docs/HANDOFF_NOTES.md — current status, known issues, suggested next tasks

---

License

MIT — see LICENSE.