https://github.com/scottconverse/civiccast
CivicCast - open-source civic broadcast platform (private development phase)
https://github.com/scottconverse/civiccast
Last synced: about 1 month ago
JSON representation
CivicCast - open-source civic broadcast platform (private development phase)
- Host: GitHub
- URL: https://github.com/scottconverse/civiccast
- Owner: scottconverse
- License: other
- Created: 2026-05-08T21:49:56.000Z (3 months ago)
- Default Branch: main
- Last Pushed: 2026-06-13T20:24:15.000Z (about 1 month ago)
- Last Synced: 2026-06-13T22:17:42.707Z (about 1 month ago)
- Language: Python
- Homepage: https://scottconverse.github.io/civiccast/
- Size: 21.9 MB
- Stars: 0
- Watchers: 0
- Forks: 0
- Open Issues: 6
-
Metadata Files:
- Readme: README.md
- Changelog: CHANGELOG.md
- Contributing: CONTRIBUTING.md
- License: LICENSE
- Code of conduct: CODE_OF_CONDUCT.md
- Audit: AUDIT_PLAYWRIGHT_INTERFACE_WIRING.md
- Codeowners: .github/CODEOWNERS
- Security: SECURITY.md
- Support: SUPPORT.md
- Governance: docs/governance/bylaws-draft.md
Awesome Lists containing this project
README
# CivicCast
**CivicCast is open-source, self-hostable civic broadcast software for public
meetings and community media.**
It helps a school board, city council, HOA board, nonprofit, public-access
station, or community media team run a meeting broadcast, preserve the record,
review captions and summaries, publish the replay, and keep a clear proof trail
without buying a proprietary broadcast appliance.
**Current release:** [`v2.1.0`](https://github.com/scottconverse/civiccast/releases/tag/v2.1.0)
**Current proof boundary:** v2.1.0 is the public beta. It validates
CivicCast-controlled local behavior — the inherited Windows new-user path from
v2.0.8, the local FileSink and loopback SRT egress proof from v2.0.9, and E.2
egress continuity against an adversarial software headend under network
impairment from v2.0.10 — and adds the beta-sprint feature set (recording
provenance, operator repair surfaces, real trim repackaging, CDN publishing,
config-gated real provider adapters, and a live caption tap) plus a
clean-machine double-click Windows install proof that reached a running service
with first-admin and recovery kit on a fresh Windows 11 VM. It does not claim
live external-provider delivery, downstream cable-headend acceptance, QAM
modulation, SDI/DeckLink output, EAS behavior, CEA-708 broadcast compliance,
app-store publication, legal certification, managed-service operation, or
production analytics proof without separate field evidence.
## Start Here
### New Users
Use this path if you want to try CivicCast as an operator or local tester.
1. Open the [latest GitHub Release](https://github.com/scottconverse/civiccast/releases/latest).
2. Download the release asset meant for your test path. Do not use the
repository source ZIP for a normal operator install.
3. Read [Install CivicCast On Windows](INSTALL-WINDOWS.md) and
[Windows Release Trust And Verification](docs/install/windows-release-trust.md).
4. Run the setup path, create the first admin, and save the recovery kit.
5. Open **System Health**, verify backup, run restore rehearsal, then run a
private first-broadcast rehearsal before using CivicCast for a real meeting.
The full operator manual is here:
- [User Manual](docs/USER-MANUAL.md), [PDF](docs/USER-MANUAL.pdf), and
[DOCX](docs/USER-MANUAL.docx)
- [Admin Guide](docs/admin-guide.md)
- [Meeting Operator Guide](docs/meeting-operator-guide.md)
- [Records Clerk Guide](docs/records-clerk-guide.md)
- [Beta Tester Start Here](docs/tester/START-HERE.md)
### Technical Users
Use this path if you are reviewing the software, running it from source, or
connecting it to a station workflow.
```bash
# One-time: install uv, then sync the workspace.
uv sync --all-extras --group dev
# Print the release version.
uv run civiccast --version
# Probe CPU, RAM, disk, GPU/VRAM, operating system, and recommended tier.
uv run civiccast doctor
# Serve the umbrella API on http://localhost:8000.
uv run uvicorn civiccast.app:app --reload
```
Without `DATABASE_URL`, CivicCast starts in local setup mode and prepares
installer-managed durable SQLite storage. Technical deployments can set
`DATABASE_URL` for Postgres. Throwaway in-memory stores are for tests and local
experiments only and require explicit acknowledgement.
Technical references:
- [Technical Operations Reference](docs/technical-ops-reference.md)
- [Architecture Overview](ARCHITECTURE.md)
- [API Guide And Generated Reference](docs/API-REFERENCE.md)
- [OpenAPI JSON](docs/openapi.json)
- [Cross-Platform Installer Guide](docs/installer/cross-platform-installer.md)
- [Channel Egress Operator And Tester Runbook](docs/ops/channel-egress-runbook.md)
- [CI And Proof Matrix](docs/releases/ci-proof-matrix.md)
## What Ships In v2.1.0
CivicCast v2.1.0 is the public beta. It includes:
- Public portal playback for live, upcoming, and published meetings, with
privacy-safe playback analytics.
- Operator workflows for setup, upload, live room, schedule, review, publish,
subscribers, and system health.
- Local captions, Spanish translation, sourced summaries, and signed record
exports.
- **Recording finalization** that picks up ended live sessions, packages HLS,
and **publishes through a selected CDN** (Bunny / Cloudflare R2) when one is
configured — with an operator **Retry** control for terminal failures.
- **Real trim repackaging**: saving a trim on a recorded asset automatically
re-renders (and re-uploads) the published recording.
- **Config-gated real provider adapters** for Internet Archive, YouTube, and
SMTP email (`CIVICCAST_PROVIDER_*=real`), with deterministic mocks remaining
the default so out-of-the-box runs stay simulated.
- A **live caption tap** (egress audio fork → durable operator review queue,
off by default) and an **ActivityPub dead-letter replay** control for
federation operators.
- **24/7 cable channel automation** (the Cablecast-replacement lane):
recurring program logs, three concurrent channels with crash auto-restart
and join-in-progress rejoin, slate/community-bulletin gap filler,
headend-grade CBR SPTS over UDP with vendor presets, and BYO-TSDuck
stream verification — proven in a monitored unattended acceptance window
(24-hour soak pending; nothing is field-proven at a headend yet).
- **Supervised BYO NDI and SDI output relays**: any channel republishes as
an NDI source or feeds a DeckLink card through the station's own FFmpeg
build (licensing means CivicCast cannot bundle those muxers), with honest
blocked states and a documented OBS bridge alternative.
- Archive and reach surfaces for the resident portal (browse by meeting
body, year, and search), local NAS, Internet Archive, YouTube,
email/webhook subscribers, podcast feeds, cable file packages, and
default-off ActivityPub federation.
- Local channel egress controls, production PlayoutSupervisor behavior, and
proof commands for FileSink continuity, loopback SRT continuity, adversarial
virtual-headend validation, fallback slate, live takeover boundaries, caption
decode-back, CG overlay lifecycle, encoder relaunch, and loudness health.
- A **clean-machine double-click Windows install proof** (fresh Windows 11 VM:
install → WSL2 helper → service → first-admin and recovery kit).
- Release evidence that distinguishes proven local paths from optional external
provider, app-store, live hardware, and production-operation lanes.
Release evidence:
- [v2.1.0 Scope And Evidence](docs/releases/v2.1.0-scope-and-evidence.md)
- [v2.1.0 Verification](docs/releases/v2.1.0-verification.md)
- [CI And Proof Matrix](docs/releases/ci-proof-matrix.md)
- [v2.1.0 GitHub Release](https://github.com/scottconverse/civiccast/releases/tag/v2.1.0)
## Architecture
CivicCast is a self-hostable FastAPI service with three React/Vite frontends:
the operator console, resident portal, and installer shell. Installer-managed
SQLite is the default local durable store; Postgres is available for technical
deployments. Media, AI, publish, archive, and egress modules are kept as
separate surfaces so each proof claim can be tested and described honestly.
```mermaid
flowchart LR
Operator["Operator console"] --> API["FastAPI umbrella app"]
Resident["Resident portal"] --> API
Installer["Installer shell"] --> API
API --> DB[("Durable storage")]
API --> Media["Media packaging"]
API --> AI["Captions, translation, summaries"]
API --> Publish["Publish and archive surfaces"]
API --> Egress["Local channel egress"]
Publish --> Portal["Public portal, NAS, IA, YouTube, email, podcast"]
Egress --> Proof["FileSink, loopback SRT, caption decode-back evidence"]
```
The architecture overview goes deeper into module boundaries, security
boundaries, deployment posture, and the current release claim:
[ARCHITECTURE.md](ARCHITECTURE.md).
## Operator Requirements
- Windows 11 with WSL2 Ubuntu 24.04 for the Windows setup path, native Linux for
CI-oriented operation, or macOS for source-build technical testing.
- Durable local storage for real operator or beta use.
- Media tooling for packaging and channel workflows.
- Approved local model bundles for summary, translation, and caption workflows.
- A first-admin account and saved recovery kit.
- Provider credentials only when a station chooses to test optional external
services.
If a required dependency is missing, CivicCast should name the dependency,
explain the next action in plain English, and leave that lane unready instead
of pretending the station is ready.
## Optional Provider Lanes
As of v2.1.0, Internet Archive, YouTube, and SMTP email ship **real adapters**
selected with `CIVICCAST_PROVIDER_*=real` plus credentials (deterministic mocks
remain the default). They are contract-tested without live external calls and
are **not yet field-proven** against the live services. These surfaces — and the
remaining scaffolded lanes — require station-specific credentials, accounts,
hardware, policies, or external systems before a public claim can be made:
- Internet Archive
- YouTube
- Email and webhook subscribers
- Podcast feed discovery
- ActivityPub federation
- Local NAS archive targets
- Cable headend delivery beyond machine-verified SPTS (no preset is
field-proven against a real headend yet)
- Receiver-side NDI proof and physical DeckLink card proof (the relays
ship; the station-side hardware evidence does not exist yet)
- Streaming-TV app-store publication
See [External Provider Proof Discussion Seed](docs/public/github-discussions/provider-proof-call.md)
for the evidence CivicCast needs before each lane is promoted from optional to
field-proven.
## Documentation
- [Documentation Index](docs/index.html)
- [User Manual](docs/USER-MANUAL.md)
- [FAQ](FAQ.md)
- [Operator Language Guide](docs/operator-language-guide.md)
- [Public Launch Draft](docs/public/civiccast-org-holding-page.md)
- [GitHub Discussion Seed Pack](docs/public/github-discussions/v2.1.0-community-seed-pack.md)
## Contributing
See [CONTRIBUTING.md](CONTRIBUTING.md). Contributions are accepted via pull
request under the Developer Certificate of Origin (DCO). Conventional Commits
are required.
## License
- **Code:** [Apache License 2.0](LICENSE-CODE).
- **Documentation:** [Creative Commons Attribution 4.0 International](LICENSE-DOCS).
- **Combined repository license:** see [LICENSE](LICENSE).
## Security
To report a security vulnerability, see [SECURITY.md](SECURITY.md). Please do
not open public issues for security reports.
## Support
See [SUPPORT.md](SUPPORT.md).
## Code Of Conduct
This project adheres to the [Contributor Covenant 2.1](CODE_OF_CONDUCT.md). By
participating, you agree to abide by its terms.