asciinema

asciinema server is a lightweight, self‑hostable platform for publishing and streaming terminal recordings. From a developer’s standpoint it is essentially a REST‑ful web service that accepts asciicast files (JSON‑encoded terminal sessions), stores them, and serves an embedded player built on web technologies. The server is written in Elixir using the Phoenix framework, which gives it strong concurrency guarantees and a clean MVC architecture. Phoenix’s channels are leveraged for live‑streaming, allowing real‑time terminal output to be pushed to connected clients with minimal latency.

Architecture

• Language & Framework: Elixir (functional, BEAM VM) + Phoenix (web sockets, templating).
• Core Libraries: The server bundles the avt virtual terminal engine (written in Go) for rendering, preview generation, and transcript extraction. Phoenix channels expose a WebSocket API for live streams.
• Persistence: PostgreSQL is the default relational store, but the codebase abstracts over Ecto so alternative adapters (MySQL, MariaDB) are possible. Recordings and streams are stored as JSON blobs in a table, with metadata fields for title, description (Markdown), visibility flags, and custom theme settings.
• Media: SVG preview thumbnails are generated on upload; plain‑text transcripts can be requested via a dedicated endpoint. No heavy media processing is required, keeping the stack lean.

Core Capabilities

• Upload API: POST /api/recordings accepts an asciicast file and returns a unique slug. Validation is performed server‑side to ensure correct format.
• Streaming API: POST /api/streams starts a live session; clients subscribe via Phoenix channels (asciinema:stream:<id>). The server forwards terminal events to all listeners in real time.
• Metadata Management: CRUD endpoints for title, description, visibility, and theme. Descriptions are Markdown‑parsed server‑side before rendering.
• Embedding: Provides an embeddable <iframe> player and a preview image URL (/preview/:id.svg). The player itself is a pure‑JS component that can be dropped into any web page.
• Security: No analytics, no third‑party cookies. Secret links can be generated for private recordings; the API supports OAuth2 integration if desired.

Deployment & Infrastructure

The application ships with a Dockerfile and docker-compose.yml, making it trivial to run in containerized environments. A typical production stack includes:

1. Elixir/Phoenix running behind a reverse proxy (NGINX/Traefik) with TLS termination.
2. PostgreSQL as the backing database, optionally backed by a managed service (e.g., Cloud SQL).
3. Redis for Phoenix channel pub/sub persistence and session storage.
4. S3-compatible object store (optional) for storing large recordings or backups.

Horizontal scaling is straightforward: Phoenix can be clustered behind a load balancer, and the database layer can be read‑replicated. Because recordings are immutable JSON blobs, they can be cached aggressively at the CDN level.

Integration & Extensibility

• Plugins: While there is no formal plugin API, the Elixir codebase can be forked and extended. The avt engine exposes a Go API that developers can wrap to create custom rendering pipelines.
• Webhooks: The server emits events (recording.created, stream.started) that can be consumed by external services via HTTP callbacks.
• CLI Integration: The asciinema CLI talks to the server over HTTP, so any language that can perform REST calls (Python, Go, Node.js) can automate uploads or stream control.
• Custom Themes: Theme CSS is served as static assets; developers can ship custom theme bundles and reference them via metadata.

Developer Experience

• Documentation: The official docs are comprehensive, covering API usage, deployment guides, and advanced configuration. The source code is well‑structured with type annotations (Elixir’s Dialyzer) and inline tests.
• Community: Active GitHub repository, issue tracker, and a Slack channel for quick support. The project is under an Apache 2.0 license, encouraging commercial use without copyleft constraints.
• Configuration: All settings (database URL, Redis host, file storage paths) are environment‑driven. The config.exs files provide sensible defaults and clear examples.

Use Cases

1. Internal Documentation: Teams can host terminal tutorials or troubleshooting guides on a private instance, ensuring compliance with corporate data policies.
2. Open‑Source Projects: Projects can embed live terminal demos in README files or docs, improving onboarding without external dependencies.
3. Educational Platforms: Instructors can stream live coding sessions or record lab exercises, providing students with reproducible terminal logs.
4. CI/CD Pipelines: Automated scripts can upload build or deployment logs to a self‑hosted server for auditability and debugging.

Advantages Over Alternatives

• Performance: Phoenix channels deliver low‑latency streaming; the BEAM VM handles thousands of concurrent connections with minimal overhead.
• Flexibility: The server exposes a clean HTTP API and WebSocket interface, making it language‑agnostic. No proprietary SDKs are required.
• Privacy & Control: All data stays on the host; there is no telemetry or advertising. The open‑source license allows unrestricted modification.
• Simplicity: No heavy video codecs or transcoding; terminal output is plain JSON, keeping storage and bandwidth