7.6 KiB

Raw Blame History

youtubedownloader

Overview

A small, self-hosted YouTube downloader with a browser interface. Paste a video URL and choose whether to download the best available audio as MP3 or the best available video with audio.

Getting Started

Prerequisites

Docker

Build

docker build -t yt-dl .

The image installs Deno as yt-dlp's JavaScript runtime. The application also allows yt-dlp to fetch its EJS challenge-solver scripts from the official yt-dlp GitHub repository when required. Together, these let yt-dlp perform the JavaScript-based signature and PO-token deciphering required by current YouTube extraction, avoiding false "This video is not available" failures for some videos. The container must be able to reach GitHub during downloads that need those scripts.

To reduce YouTube PO-token and rate-limit failures, downloads try the Android, iOS, and TV player clients before the web client. This is a best-effort mitigation; YouTube's anti-bot requirements change and the client order may need retuning in the future.

Run

docker run --rm -p 8080:8080 yt-dl

Open http://localhost:8080 in a browser, paste a YouTube URL, then select Download MP3, Download Video, or Download Video 720p. The 720p option caps the video at 720p and falls back to the best available lower quality when the source has no 720p stream; it otherwise uses the same progress, automatic delivery, and sanitized filename behavior as the unrestricted Video option.

Downloads run as temporary in-memory jobs, so a progress bar shows percentage, speed, and downloaded size while the server prepares the file. When it finishes, the file is delivered to your browser automatically. Large videos and higher-quality formats can take several minutes, depending on the source video and your network connection.

The browser starts a download with POST /download, polls GET /progress/{job_id}, and retrieves the completed file from GET /download/{job_id}/file. Job state and temporary files are removed after delivery (or after a timeout for abandoned jobs), and are not retained across server restarts.

If a pasted video link includes playlist context (such as a list= parameter), the app downloads only that referenced video. Downloaded files use the video title, with emoji and unsupported symbols removed while normal letters (including non-Latin characters), digits, and common punctuation are retained. An emoji-only title falls back to the video ID.

AI Workflow

This project includes the persistent planner/implementer/reviewer workflow with file-based coordination, plus the PO orchestration layer. Manual and auto are two runtime modes for the same scaffold: they use the same generated files, task board, and review gate. Fewer role sessions means less coordination overhead and lower token cost.

Runtime modes

Manual mode: start the planner, implementer, and reviewer in separate terminals, then drive each session yourself with the documented text commands.
Auto mode: run aide po to start the PO session, which uses MCP tools to coordinate the post-planning implementer/reviewer workflow for you.

Concepts

Cycle — a unit of work on a feature branch. One cycle = one branch = one PR.

Roles and file ownership:

Role	Reads	Writes
PO	`.ai/TASKS.md`, `.ai/PLAN.md`, `.ai/REVIEW.md`, `.ai/prompts/po.md`	MCP session commands via `aide po`
Planner	`ROADMAP.md`	`.ai/PLAN.md`, `.ai/TASKS.md`
Implementer	`.ai/PLAN.md`, `.ai/REVIEW.md`	source code, `.ai/TASKS.md`
Reviewer	`.ai/PLAN.md`, commits	`.ai/REVIEW.md`, `.ai/TASKS.md`

Status flow:

in_planning → ready_for_implement → in_implementation → ready_for_review → in_review → ready_to_commit → done
                                          ↑                                     |
                                          └──── changes_requested ◄─────────────┘

Start a new development cycle

# Edit ROADMAP.md with your goals first, then:
aide cycle start feature/<scope>

Start persistent role sessions (manual mode)

aide plan          # terminal 1
aide implement     # terminal 2
aide review        # terminal 3

Launch each role once, then keep those sessions open for the rest of the cycle.

Role launchers read default agent/model settings from .ai/config.json. To override, pass the agent first, then any CLI flags. Example: aide review claude --model sonnet Claude starts interactively by default, and the Codex launcher uses interactive codex mode so the session stays open for role commands.

Start the PO orchestrator (auto mode)

aide po

The PO session drives the post-planning task board flow through the aide MCP server. By default, aide po launches Claude with --model haiku, and aide po codex launches Codex with -m gpt-5.4-mini. .ai/config.json can override those defaults, and an explicit CLI --model or -m flag takes precedence. If no tasks are in ready_for_implement or later, run the planner first. The MCP server appends structured debug logs to .ai/mcp-server.log, and the scaffold gitignore excludes that file.

Drive work inside the existing sessions

planner> start_plan
implementer> next_task T-001
reviewer> next_task T-001
implementer> commit_task T-001
implementer> rework_task T-001
aide cycle end 0.7.0

Cross-platform CLI equivalents: aide cycle end [VERSION] closes the cycle outside the persistent role session, and aide pr [--dry-run] creates or updates the branch PR.

Planner commands:

Before start_plan, freeform conversation with the planner is the roadmap-refinement phase. Use it to sharpen scope, acceptance criteria, constraints, and trade-offs directly in ROADMAP.md. start_plan is the explicit handoff into formal planning.

Command	Description
`start_plan`	Read `ROADMAP.md`, write `.ai/PLAN.md` and `.ai/TASKS.md`
`rework_plan [TASK_ID]`	Revisit the plan when scope or approach changes

Implementer commands:

Command	Description
`next_task [TASK_ID]`	Pick up the next `ready_for_implement` task
`commit_task [TASK_ID]`	Turn a `ready_to_commit` task into one clean final commit, including task-specific `.ai/` artifacts
`rework_task [TASK_ID]`	Address `changes_requested` findings from `.ai/REVIEW.md`
`aide cycle end [VERSION]`	Close the cycle after all tasks reach `done`, committing remaining `.ai/` artifacts with a `Release-As:` footer
`status_cycle [TASK_ID]`	Show task status and recommended next action

Reviewer commands:

Command	Description
`next_task [TASK_ID]`	Pick up the next `ready_for_review` task and run review plus verification
`status_cycle [TASK_ID]`	Show task status and recommended next action

File map

File	Purpose	Tracked
`.ai/PLAN.md`	Current plan	yes
`.ai/TASKS.md`	Task board with status	yes
`.ai/prompts/po.md`	PO orchestration prompt for auto mode	yes
`.ai/REVIEW.md`	Review findings	yes (tracked cycle log)
`.ai/HANDOFF.md`	Runtime handoff log	yes (tracked cycle log)
`.ai/config.json`	Per-role launch defaults	yes
`ROADMAP.md`	Cycle goals (edit before planning)	yes
`AGENTS.md`	Project-specific and workflow-managed agent rules	yes
`CLAUDE.md`	Agent instruction entry point (`@AGENTS.md`)	yes
`aide po`	Launch the PO orchestration session	yes

Create a PR

aide pr

Full workflow details and session recovery rules are in AGENTS.md.

7.6 KiB Raw Blame History