circle-course-downloader 0.1.3

Personal downloader for Circle course lesson videos accessible from your own account.

Circle Course Downloader

A small, practical CLI for saving Circle course videos that you can already access with your own account.

Circle Course Downloader opens a dedicated Chromium profile, lets you sign in normally, discovers course lessons through the authenticated page, and downloads the video streams with yt-dlp. It is built for personal offline viewing, backups, and unreliable connections.

This project is unofficial and is not affiliated with Circle. It does not bypass DRM, paywalls, 2FA, captchas, or access controls. Use it only for content you are authorized to view and download.

Highlights

• Browser-only authentication: no terminal passwords, copied cookies, or pasted tokens.
• Reusable local session stored in a dedicated Playwright Chromium profile.
• Course lesson discovery from real Circle course pages.
• Video URL detection for Circle HLS, direct video links, YouTube, Vimeo, Wistia, Loom, Mux, and Cloudflare Stream.
• yt-dlp downloads with resume support and MP4 merge output.
• manifest.json and manifest.csv exports for auditing what was found.
• Dry-run mode for inspecting generated download commands before saving media.

Installation

Install the package and the Playwright browser runtime:

python -m pip install circle-course-downloader
python -m playwright install chromium

Python 3.11 or newer is required.

Quick Start

Run the downloader with a full Circle course URL:

circle-course-downloader download "https://your-community.example.com/c/course-slug"

On the first run, a Chromium window opens. Sign in to Circle in that browser, return to the terminal, and press Enter.

After that, the CLI reuses the same dedicated browser profile for future downloads:

circle-course-downloader download "https://your-community.example.com/c/another-course"

Downloaded videos are saved to downloads/ by default.

How It Works

1. Opens the requested Circle course page in a persistent Chromium profile.
2. If login is required, waits while you authenticate in the browser.
3. Saves the browser session under .auth/.
4. Discovers lesson links from the course page.
5. Visits each lesson, finds candidate video URLs, and classifies the provider.
6. Writes a manifest and downloads each available video with yt-dlp.

The default local files are:

.auth/session-browser-profile/
.auth/session.json
downloads/manifest.json
downloads/manifest.csv
downloads/01 - Lesson title.mp4

Generated manifests can contain signed media URLs. Do not publish or commit them.

CLI Usage

circle-course-downloader download [OPTIONS] COURSE_URL

Option	Description
--output-dir PATH	Save videos and manifests somewhere other than downloads/.
--session PATH	Use a different exported session file. The browser profile is stored next to it.
--force-login	Delete the saved auth state and open a fresh visible login browser.
--headless	Run Chromium without a visible window after a saved browser profile exists.
--dry-run	Discover lessons and print the yt-dlp commands without downloading videos.

Examples:

circle-course-downloader download "https://your-community.example.com/c/course-slug" --dry-run
circle-course-downloader download "https://your-community.example.com/c/course-slug" --output-dir "./my-videos"
circle-course-downloader download "https://your-community.example.com/c/course-slug" --force-login
circle-course-downloader download "https://your-community.example.com/c/course-slug" --headless

--headless is useful only after a saved browser profile already exists. First login always uses a visible browser window.

Install From Source

Clone the repository, create a virtual environment, install the package, and install Chromium for Playwright:

python -m venv .venv
.\.venv\Scripts\python -m pip install .
.\.venv\Scripts\python -m playwright install chromium

Then run the CLI from the virtual environment:

.\.venv\Scripts\circle-course-downloader download "https://your-community.example.com/c/course-slug"

For development and publishing tools:

.\.venv\Scripts\python -m pip install -r requirements.txt

Development

Run the local checks before opening a pull request:

.\.venv\Scripts\python -m pytest
.\.venv\Scripts\python -m compileall .\src
.\.venv\Scripts\python -m build
.\.venv\Scripts\python -m twine check dist/*
.\.venv\Scripts\circle-course-downloader --help
.\.venv\Scripts\circle-course-downloader download --help

The package metadata is defined in pyproject.toml, and the CLI entry point is:

circle-course-downloader = circle_courses_downloader.cli:main

Safety And Privacy

Circle Course Downloader uses its own Chromium profile under .auth/. It does not read cookies, sessions, or tokens from your default browser.

Contributing

Contributions are welcome when they keep the project focused on the browser-only Circle course download flow.

Good first improvements include:

• Better provider detection for embedded video platforms.
• Clearer error messages for expired sessions or unavailable lessons.
• More fixture-based parser tests.
• Cross-platform documentation polish.

Please read CONTRIBUTING.md and SECURITY.md before opening a pull request.

License

MIT. See LICENSE.