tools.youtube_describe module

Analyse a video via the Gemini API — YouTube (native ingestion), Rumble, Twitch, direct MP4, and 1000+ other sites via yt-dlp.

async tools.youtube_describe.run(video_url='', youtube_url='', focus_area=None, ctx=None)[source]

Tool entry point: produce an exhaustive Gemini analysis of a video URL.

Orchestrates the whole pipeline: it classifies the URL via _classify_url(), resolves a Gemini key (preferring the user’s stored key over the rotating default pool, with per-user default-key rate limiting via manage_api_keys), fetches metadata with _get_video_metadata(), enforces MAX_DURATION_SECONDS, picks an FPS with _calculate_fps(), and builds the prompt from _format_metadata_for_prompt() plus ANALYSIS_PROMPT and any focus_area. YouTube URLs take a fast native Gemini ingestion path; everything else downloads (_download_direct() or _download_with_ytdlp()), uploads via _upload_to_gemini_sync(), and cleans up both the temp directory and the Gemini-hosted file in a finally block. The actual model call goes through _generate_description().

Registered under TOOL_NAME = "describe_video" and discovered by tool_loader.load_tools; the inference worker dispatches it through the ToolRegistry with a populated ctx. It reads/writes per-user API-key and usage state in Redis via ctx.redis, touches the filesystem for temporary downloads, and makes outbound HTTP/Gemini calls.

Parameters:

  • video_url (str) – The video URL to analyse (primary argument).

  • youtube_url (str) – Legacy alias accepted when video_url is absent.

  • focus_area (Optional[str]) – Optional aspect to give extra depth in the analysis.

  • ctx – Tool execution context supplying redis, user_id, channel_id, and config for key resolution and limits.

Returns:

A JSON document. On success it carries success: true with the description, model_used, source, and available metadata; on failure it carries an error message (missing URL, unextractable ID, over-length, rate-limit, download/upload, or generation error).

Return type:

str