How jay-k-crest/meetbot works
1. What this repo is
- Meet Bot is a local meeting recording tool for Google Meet, Zoom Web, and Microsoft Teams Web.
- The architecture is centered on two external capabilities: browser automation to join a meeting, and FFmpeg-based capture to record the local screen/audio on Windows.
2. Primary entrypoint
- bot.py is the top-level executable entrypoint shown in the README.
- It likely delegates into the meetbot package, where CLI parsing and orchestration are split into smaller modules.
3. CLI and orchestration boundary
- meetbot/cli.py appears to own command-line parsing and command selection:
- direct meeting URL mode
- calendar-driven mode (--from-calendar)
- meetbot/runner.py is likely the main coordinator that ties together meeting discovery, browser joining, waiting logic, and recording lifecycle.
4. Configuration and environment
- meetbot/env.py and meetbot/config.py define the boundary between runtime configuration and business logic.
- The repo is driven by .env values such as:
- calendar identifiers
- OAuth credential/token file paths
- lookahead and timeout values
- output location
- This keeps secrets, timing, and environment-specific paths out of the orchestration code.
5. Calendar-based meeting discovery
- meetbot/calendar_service.py is the integration layer with Google Calendar API.
- It is responsible for finding the next relevant meeting event based on:
- CALENDAR_ID
- LOOKAHEAD_HOURS
- optional EVENT_QUERY
- This module forms a distinct external-service boundary: if the bot is launched “from calendar,” this is the only place that should know about Google authentication and event retrieval details.
6. Browser automation layer
- meetbot/browser_helpers.py encapsulates Playwright/browser setup and generic interaction helpers.
- meetbot/selectors.py likely stores provider-specific selectors or locator definitions for Meet/Zoom/Teams.
- This split is important: browser lifecycle and common actions live separately from the DOM details that vary by meeting provider.
7. Recording subsystem
- meetbot/recorder.py is the capture layer and likely wraps the FFmpeg process invocation.
- The README indicates Windows-specific capture assumptions:
- gdigrab for screen capture
- dshow for audio capture
- This module is a hard boundary around OS/media tooling and is the part that turns a joined meeting into an output file.
8. Meeting execution flow
- The typical runtime flow is:
1. CLI receives either a meeting URL or a calendar lookup request.
2. Config/env is loaded.
3. If calendar mode is used, the next event is fetched from Google Calendar.
4. The browser automation layer opens the meeting URL and joins.
5. The runner waits through join/lobby/admit states using configured timeouts.
6. The recorder starts and writes the output file, usually under recordings/.
9. Two input paths, one execution pipeline
- The repo supports two sources of meeting context:
- direct URL input
- calendar-derived URL/event metadata
- Both converge into the same downstream pipeline: browser join + recording.
- This is a clean architectural seam: meeting discovery is separate from meeting execution.
10. Provider-specific behavior
- Google Meet, Zoom Web, and Teams Web share the same high-level flow, but their join pages and controls differ.
- selectors.py likely exists to isolate those differences so the runner does not contain provider-specific DOM logic.
11. External dependencies that shape the architecture
- Playwright is the browser automation runtime.
- Google Calendar API is the scheduling source when not using a direct URL.
- FFmpeg is the capture engine.
- Windows is a first-class platform constraint because the README calls out gdigrab/dshow.
- Chromium binaries are required for Playwright, so browser installation is part of deployment/runtime setup.
12. Operational concerns
- Timeouts and lead times are explicit configuration points:
- join early
- join timeout
- admit/lobby timeout
- This suggests the runner is designed around asynchronous waiting and state transitions rather than a simple linear script.
13. Auth and token lifecycle
- Calendar access uses OAuth credentials and a persisted token file.
- The first calendar-based run triggers browser-based login and then writes a token for later runs.
- That makes authentication a separate initialization concern from the normal meeting-recording path.
14. Useful diagram boundaries
- A good architecture diagram should show four main boxes:
- CLI / command entry
- Calendar integration
- Browser join automation
- FFmpeg recorder
- With runner.py as the coordination layer connecting them, and config.py/env.py as shared configuration inputs.
Main entry points: runner.py Runner · cli.py CLI · config.py Config · calendar_service.py Calendar
Components 9
Command entry
Top-level CLI and runtime kickoff.
Orchestration
Shared execution flow and runtime coordination.
- Runner · Coordinates discovery, join, waiting, and recording.
meetbot/runner.py
External integrations
Calendar, browser, and recording boundaries.
Connections 14
- bot.py → CLI: launches · Top-level executable hands off to CLI parsing.
- CLI → Config: loads · CLI uses runtime configuration values.
- CLI → Env: reads · CLI boundary includes environment-backed settings.
- CLI → Runner: dispatches · Selected command mode is forwarded to the orchestrator.
- Runner → Config: consumes · Runner uses shared timing and output settings.
- Runner → Calendar: queries · Calendar mode resolves a meeting event first.
- Runner → Browser: joins via · Runner delegates meeting navigation to browser automation.
- Browser → Selectors: uses · Browser actions rely on provider-specific locators.
- Runner → Recorder: starts · Once joined, the runner launches capture.
- Calendar → Env: auth · Calendar access depends on OAuth and token paths.
- Calendar → Config: filters · Lookup behavior is driven by lookahead and query settings.
- Recorder → Config: writes to · Capture output location comes from configuration.
- Runner → Browser: waits on · Runner coordinates join, lobby, and admit waits.
- Runner → Selectors: provider rules · Provider-specific behavior influences join flow decisions.