Skip to main content
Glama

demoreel

Upload a CS2 demo. Get the match metrics and the highlight videos back — automatically.

demoreel is a self-hosted service that ingests Counter-Strike 2 demos (.dem), computes scoreboard-grade statistics, detects the moments worth watching, and renders them to video. It is built to be driven by software as much as by people: a REST API, webhooks, and an MCP server so LLM agents can query a match and edit its highlights.

            ┌────────────┐   analyze    ┌──────────────────────┐
 .dem ────▶ │  REST API  │ ───────────▶ │ stats · rounds · kills│ ──▶ JSON (API / MCP / web UI)
 upload     │  MCP · UI  │   job queue  │ highlight candidates  │
            └────────────┘              └──────────┬───────────┘
                  ▲                                │ highlight = editable spec
                  │ edit ops (trim, POV, speed…)   ▼ (segments: ticks, POV, speed, caption)
             humans / agents            ┌──────────────────────┐
                                        │ renderers            │ ──▶ mp4 + thumbnail
                                        │  ingame (CS2 POV)    │
                                        │  radar  (2D replay)  │
                                        └──────────────────────┘

Status: early (v0.1). Analysis, highlight detection, the API, MCP server, web UI and the 2D renderer work end to end on real demos. The in-game (first-person) renderer has produced correct clips on Windows with the current CS2 build (single and multi-take, from the CLI and through the server), on one machine so far — see what is and is not verified in docs/ingame-recording.md, and the roadmap.

What you get

  • Match metrics — score by half and side, per-round economy and outcome, and per player: K/D/A, ADR, KAST, HS%, rating (HLTV 2.0 approximation), opening duels, trades, multi-kills, clutches (1vX), utility damage, flashes, accuracy, weapon breakdown, CT/T split.

  • Automatic highlights — aces and multi-kills, won clutches, flashy single kills (noscope, through smoke, wallbang, blind, airborne, knife, zeus), ninja defuses; each scored and described, with tight clip boundaries (kills far apart become separate segments).

  • Highlight videos from two renderers:

    • ingame — the real game, from the player's point of view (needs a PC with CS2);

    • radar — a 2D tactical replay with rosters, kill feed, utility and bomb, which runs anywhere (no game, GPU or display — fine in a container).

  • Finished, branded videos — give the instance a brand kit (logo + colours) and every video gets an animated intro and outro generated from the logo (with synthesised sound), a HUD in the community's identity (score, nameplate, kill counter), captions and real slow motion. White-label: no third-party watermark. See docs/branding.md.

  • Ready to post — every play in 16:9 and in 9:16 laid out for phones (and 1:1), cut from the same recorded footage; one call produces a whole match.

  • Import from your community's site — point a small JSON file at a site that lists matches and demo links, and import a night's games in one click (or one MCP call). Imports are throttled and stop at the first sign that the site is overloaded.

  • Edits without the game — first-person captures are kept as masters with handles, so trimming, slowing down, captioning or re-branding a clip re-renders in seconds without launching CS2 again.

  • Editable highlights — a highlight is a small declarative spec. Trim it, change POV, slow it down, add a caption, split or reorder segments through validated operations, then re-render. Reels stitch several highlights into one video.

  • Agent-friendly by design — MCP tools with compact outputs, job handles you can block on instead of polling, actionable error messages, /llms.txt, a complete OpenAPI contract.

  • Async everything — uploads and renders return a job; long-poll it or subscribe with webhooks.

  • One install, no infrastructure — SQLite and a DB-backed queue by default (no Redis). Windows and Linux.

Related MCP server: Botverse

Quick start

Requirements: uv (it brings its own Python). ffmpeg is bundled.

git clone <this-repo> demoreel && cd demoreel
uv sync
uv run demoreel serve

Open http://127.0.0.1:8000, drop a demo, watch the highlights. API docs live at /docs.

No server, just the terminal:

uv run demoreel analyze path/to/match.dem                 # scoreboard + highlights
uv run demoreel render  path/to/match.dem -o reel.mp4     # top highlights as one video
uv run demoreel doctor                                    # what this machine can do

Docker (API + worker + 2D renderer): docker compose up --build.

Using the API

# 1. upload → 202 with a match and a job
curl -F "file=@match.dem" http://127.0.0.1:8000/api/v1/matches

# 2. wait for the analysis (long-poll, no busy loop)
curl "http://127.0.0.1:8000/api/v1/jobs/<job_id>?wait=60"

# 3. read
curl http://127.0.0.1:8000/api/v1/matches/<match_id>/scoreboard
curl http://127.0.0.1:8000/api/v1/matches/<match_id>/highlights

# 4. edit a highlight: start 1s later, slow-mo on the final second, add a caption
curl -X POST http://127.0.0.1:8000/api/v1/highlights/<id>/edit -H "content-type: application/json" -d '{
  "ops": [
    {"op": "trim", "segment": 0, "start_delta_s": 1.0},
    {"op": "split_segment", "segment": 0, "at_tick": 74560},
    {"op": "set_speed", "segment": 1, "speed": 0.5},
    {"op": "set_caption", "segment": 1, "caption": "1v2 on the pistol round"}
  ]}'

# 5. render → 202 with a job; when done, the render has a video_url
curl -X POST http://127.0.0.1:8000/api/v1/highlights/<id>/renders -H "content-type: application/json" \
     -d '{"renderer": "radar"}'

Everything else (custom highlights from any tick range, reels, kill search, the plays feed, match sources, the brand, webhooks, capabilities) is in the interactive docs at /docs and summarised for machines at /llms.txt.

Using it from an LLM agent (MCP)

The API process serves MCP over Streamable HTTP at /mcp; demoreel mcp speaks stdio for local clients.

# Claude Code, remote/HTTP
claude mcp add --transport http demoreel http://127.0.0.1:8000/mcp

# Claude Code / Claude Desktop, local stdio (run from the repo so it finds the same data dir)
claude mcp add demoreel -- uv run --directory /path/to/demoreel demoreel mcp

Tools: list_matches, get_match, get_player_stats, list_rounds, get_round, search_kills, list_highlights, get_highlight, create_highlight, edit_highlight, delete_highlight, render_highlight, render_reel, get_job, get_render, cancel_job, get_feed, list_source_matches, import_matches, import_demo, produce_match, get_brand, get_capabilities, list_nights, get_rivalries, get_player_profile, get_trophies, get_chat_rankings (insights across matches: who owns whom, each night's trophies, the cry-baby ranking of the chat — see docs/metrics.md) — plus a make_highlight_reel prompt and the full analysis as a resource. Then just ask:

"Look at the last match, find biruta's best moment, cut it down to the three kills, slow down the last one and give me the video."

More in docs/agents.md.

Renderers

ingame

radar

Output

Real CS2 footage, player POV

2D top-down tactical replay

Needs

Windows/Linux PC with CS2, GPU, desktop session

Nothing (CPU only)

Speed

Slow (launches the game)

~1× real time on a desktop CPU

Enable

DEMOREEL_INGAME_ENABLED=1 + setup in docs/ingame-recording.md

Always on

renderer: "auto" (the default) uses ingame when the server can, otherwise radar. Workers advertise capabilities, so a Linux server can analyze and render 2D while a gaming PC runs demoreel worker -c ingame against the same database and records the first-person clips.

Radar images are Valve assets and are not in this repository; they are downloaded on first use from the awpy-data releases into the data directory (DEMOREEL_OFFLINE=1 disables that and renders on a plain grid).

Configuration

Environment variables (or a .env file) — see .env.example. The ones you will touch first: DEMOREEL_DATA_DIR, DEMOREEL_PUBLIC_URL, DEMOREEL_API_KEY, DEMOREEL_AUTO_RENDER_TOP, DEMOREEL_DEFAULT_RENDERER, DEMOREEL_INGAME_ENABLED.

Security note: with no DEMOREEL_API_KEY the API is open — fine on 127.0.0.1, not on a network. Demos contain player names and SteamIDs; treat the data directory accordingly.

How it works

  • Parsing — demoparser2 (Rust) behind a defensive wrapper that handles warm-up, knife rounds and restarts, side swaps, missing events and bots (analysis/parser.py). A 40-minute match analyzes in ~10 s.

  • Stats — analysis/stats.py; definitions are documented in the code and in docs/metrics.md.

  • Highlights — analysis/highlights.py: one candidate per (round, player), scored by kills, speed, flashiness, clutch size and round context.

  • Jobs — a table and an atomic claim query (jobs.py); worker processes with capabilities, heartbeats, re-queue on worker loss.

  • Rendering — a tiny Renderer protocol; radar draws with skia and pipes frames to ffmpeg; ingame drives CS2 following cs-demo-manager's approach.

  • Front-ends — FastAPI (api.py), MCP (mcp_server.py), Typer CLI, and a no-build static web UI — all thin layers over service.py.

  • Composition — compose/: logo splitting, procedural bumpers and sound, HUD, retiming, masters, final assembly. Capture answers "what did the game look like"; composition answers "what does the video look like".

Architecture notes: docs/architecture.md · brand kits and composition: docs/branding.md · speed and scale: docs/performance.md · UI design rationale: docs/design/frontend-design-plan.md.

Development

uv sync
uv run pytest            # tests needing a real demo run only if you put .dem files in demos/
uv run ruff check src tests

See CONTRIBUTING.md. The plan — in particular in-game recording hardening and automatic editing (intro/outro bumpers, per-client/map/situation templates, music, transitions, speed ramps) — is in ROADMAP.md.

Acknowledgements

  • demoparser2 (MIT) — the demo parser.

  • cs-demo-manager (MIT) by AkiVer — the in-game recording flow (playback plugin, actions file, startmovie pipeline) is ported from it.

  • awpy / awpy-data (MIT) — map calibration and radar extraction.

  • Barlow by Jeremy Tribby (SIL OFL 1.1) — the typeface bundled for videos and UI.

  • reka-ai/cs2-dem-renderer (MIT) — evidence that this recording technique scales on Linux, and the streaming-encode design the performance plan follows.

  • Ideas on highlight scoring and recording pitfalls were informed by reading cs2-highlights-maker, CS2-insight-agent and cs-demodesk; no code from those projects is included.

demoreel is not affiliated with Valve. Counter-Strike is a trademark of Valve Corporation.

License

MIT

Available Tools

30 tools
cancel_jobB
Destructive

Cancel a queued or running job.

Inputs: job_id (required). Returns: object

create_highlightA

Create a custom highlight. Three ways: (1) segments = explicit list; (2) start_tick + end_tick (+ pov) for one continuous moment; (3) round_number + player to auto-clip that player's kills in that round. Returns the new highlight (not rendered yet).

Inputs: match_id (required), pov, tags, title, +6 more. Returns: object

delete_highlightA
Destructive

Delete a highlight definition (its rendered videos are kept).

Inputs: highlight_id (required). Returns: object

edit_highlightA

Edit a highlight with a list of operations applied in order (all-or-nothing). Operations: trim{segment,start_delta_s,end_delta_s} · set_range{segment,start_tick,end_tick} · set_pov{segment|null,steamid} · set_speed{segment|null,speed} · set_caption{segment,caption} · add_segment{start_tick,end_tick,pov_steamid,speed,caption,index} · remove_segment{segment} · move_segment{segment,to} · split_segment{segment,at_tick} · set_meta{title,description,tags}. Segment indexes are 0-based. Example slow-motion on the last second of segment 0 that ends at tick 5000: [{op:'split_segment',segment:0,at_tick:4936},{op:'set_speed',segment:1,speed:0.5}]. Call render_highlight afterwards to produce the new video.

Inputs: ops (required), highlight_id (required). Returns: object

get_brandA
Read-only

Identity of this instance: the community's name, tagline, site, colours and logo. Videos carry this brand automatically (animated intro/outro built from the logo, HUD, captions); use the name and tone when writing titles or captions.

Inputs: no named parameters. Returns: object

get_capabilitiesB
Read-only

Server capabilities: which renderers are available here and why not.

Inputs: no named parameters. Returns: object

get_chat_rankingsA
Read-only

All-chat rankings for friends to tease each other (a word list, NOT moderation - it misses sarcasm). Podiums: toxic ('boca suja': swearing), whine ('chorão': cheating accusations, luck, complaining), death_cry (whining or swearing within 20 s of his own death - the real cry-baby number), talker ('tagarela': who types the most lines, whatever they say; no examples), laugh ('risadinha'), nice ('gente boa': praise, gg), shouting (caps). Each podium entry has the count, the rate per round played and one or two example lines (slurs masked). players has every count per player.

Inputs: limit, night, since, until, +1 more. Returns: object

get_feedA
Read-only

The best plays that already have a video, across all matches, best first. Each item has the play (player, kind, round, tags), its match and the video_url. Use it to answer 'show me the best plays' or 'what did do lately' without walking every match.

Inputs: kind, limit, player. Returns: result

get_highlightA
Read-only

Full highlight: description, every segment (ticks, POV, speed, caption), kill ticks and all its renders. Read this before editing.

Inputs: highlight_id (required). Returns: object

get_jobA
Read-only

Status of an analysis or render job. wait_seconds blocks until it finishes (max 120) — prefer this over polling in a tight loop.

Inputs: job_id (required), wait_seconds. Returns: object

get_matchB
Read-only

Match overview: status, map, teams, scoreboard (K/D/A, ADR, KAST, rating per player) and the top highlights. Start here.

Inputs: match_id (required). Returns: object

get_player_profileB
Read-only

One player across matches: matches, wins, K/D/A, ADR, KAST and rating (weighted by rounds), HS%, clutches, opening duels, multi-kills, best plays (highlight ids and scores), fails by kind, nemesis and favourite victim, chat numbers and the last matches. No filter = every match he played.

Inputs: player (required), night, since, until, +1 more. Returns: object

get_player_statsB
Read-only

Every stat of one player: rating, ADR, KAST, opening duels, trades, multi-kills, clutches, utility, per-weapon kills, CT/T split.

Inputs: player (required), match_id (required). Returns: object

get_renderC
Read-only

A rendered video: status, video_url, thumbnail_url, size, and whether it is stale (highlight edited after rendering).

Inputs: render_id (required). Returns: object

get_rivalriesA
Read-only

Who kills whom across matches. pairs: two players, kills of each on the other (score, the one ahead first), matches they faced each other, opening kills and knife/Zeus kills of each on the other, imbalance (0 even, 1 one-way). players: each player's nemesis ('carrasco', who beats him the most) and favourite victim ('freguês') as 'name (his kills-his deaths)'. No filter = every match; pass player for one player's rivalries. sort: duels (most kills between them) | diff | imbalance.

Inputs: sort, limit, night, since, +4 more. Returns: object

get_roundB
Read-only

Full detail of one round: every kill (tick, weapon, headshot, wallbang, smoke, trade…), clutches, bomb events, economy.

Inputs: match_id (required), round_number (required). Returns: object

get_trophiesA
Read-only

Trophies of one match (match_id) or one night (night; default: the most recent night): MVP, clutch king, entry fragger, longest kill streak, longest drought, kills on 10 HP or less, friendly flasher, friendly fire, best and worst aim, died with the knife out, baiter, economist, headshot machine. Each has titles in Portuguese and English, the winner, the value, the numbers behind it and the runners-up; a trophy nobody deserved is left out.

Inputs: night, match_id. Returns: object

import_demoA

Analyze a demo file that already exists on the server's disk (inside one of the configured import folders). To upload from elsewhere use the REST API: POST /api/v1/matches (multipart field file). Returns match_id and job_id; wait with get_job, then call get_match.

Inputs: path (required), auto_render_top. Returns: object

import_matchesA

Download and analyze matches from a source (see list_source_matches). Returns one job per match; wait with get_job, whose result carries the new match_id. Matches already imported or without a demo are reported in skipped.

Inputs: source_id (required), remote_ids (required), auto_render_top. Returns: object

list_highlightsA
Read-only

Highlights of a match, best first, with video URL when rendered. score is 0-100 and tier S/A/B/C; featured plays are the curated best of each team plus stand-out plays - they get first-person videos, the others only 2D replays. get_highlight shows the score breakdown (feat, impact, style, economy, stakes, outcome). Pass featured=true for just the curated ones.

Inputs: match_id (required), kind, limit, player, +2 more. Returns: result

list_matchesB
Read-only

List analyzed matches (newest first) with map, score and status.

Inputs: limit, status. Returns: result

list_nightsA
Read-only

Nights of play, newest first: date, match ids, maps, how many players and rounds. A night is every match from noon to noon, so games after midnight count for the evening before. Use the date as night in get_trophies / get_rivalries / get_chat_rankings / get_player_profile.

Inputs: no named parameters. Returns: result

list_roundsA
Read-only

One line per round: winner, reason, score, buys, bomb, first kill, tick range. Use get_round for the kill-by-kill detail.

Inputs: match_id (required). Returns: result

list_source_matchesA
Read-only

Sites this server can import matches from (for example the community's own match history), and for one source the matches it lists with their import status here. Call without source_id to list sources.

Inputs: limit, source_id, only_missing. Returns: object

produce_matchA

Make the videos of a match in one call: 2D replays ('radar') of every highlight and first-person POV ('ingame') of the featured ones - pov='all' records every play instead - in each shape ('16:9', '9:16' ready to post on phones, '1:1'). Videos that already exist and are up to date are skipped. First-person plays without recorded footage are captured together in one game session (capture_job_id, wait with get_job); their videos are queued when it finishes. detail explains anything that could not be queued (for example: recording is not enabled here).

Inputs: match_id (required), pov, force, formats, +2 more. Returns: object

render_highlightA

Render a highlight to an mp4 (asynchronous). renderer: 'auto' (in-game POV if this server can, else 2D), 'radar' (2D tactical replay; extra: {camera:'follow'|'full', zoom:1-3}) or 'ingame' (real CS2 footage, slower). Returns job_id; if wait_seconds > 0 it waits and includes video_url when done.

Inputs: highlight_id (required), fps, extra, width, +3 more. Returns: object

render_reelB

Render a reel: several highlights back to back in one video, with title cards. Pass highlight_ids for an explicit order, or let the server pick the top best (optionally only for one player).

Inputs: match_id (required), fps, top, extra, +7 more. Returns: object

rescore_matchA

Re-run the highlight scoring and curation on a match that is already analyzed (fast, the demo is not read again). Highlights keep their ids and videos; featured plays chosen by hand are kept.

Inputs: match_id (required). Returns: object

search_killsC
Read-only

Search the kill log. All filters are optional and combined with AND.

Inputs: match_id (required), limit, victim, weapon, +6 more. Returns: result

Tool Schema Changelog

Recent tool additions, removals, and schema changes observed during successful MCP inspections.

Loading tool schema changelog…

    TDQS

    B3.4/5.0

    Scored across 30 tools

    Disambiguation4/5

    Most tools map to clearly distinct resources or actions: matches, rounds, kills, highlights, players, jobs, renders, imports and analytics. A few pairs such as get_player_stats vs get_player_profile and get_feed vs list_highlights need the descriptions to separate them, but the boundaries are still workable.

    Naming Consistency5/5

    The tool set uses a consistent snake_case verb_noun pattern throughout: list_matches, get_match, create_highlight, render_reel, import_demo, get_player_profile, and so on. Minor variations like set_featured and produce_match still fit the same predictable convention.

    Tool Count2/5

    Thirty tools is heavy for an agent-facing surface, even though the server spans demo import, analysis, highlight editing, rendering, jobs and community analytics. Many related operations could be consolidated or grouped, and the size increases selection burden.

    Completeness4/5

    The surface covers the domain well: importing demos and source matches, match/round/kill/player analysis, highlight CRUD, featured curation, rendering, job status, feeds, trophies, rivalries and chat rankings. Minor gaps remain, such as no direct upload tool, no match deletion/metadata management, and limited source administration.

    Maintenance

    ActivityMaintained
    ResponsivenessNo recent community issues

    Related MCP Connectors

    Related MCP Servers