get_caption_content

Extract video caption text or download subtitle files to read transcripts, analyze spoken content, and create accessible media.

Instructions

Get actual CAPTION TEXT or download captions file. USE WHEN: Reading video transcript, downloading subtitles, analyzing spoken content, creating accessible content. RETURNS: Full caption text and download URL. EXAMPLE: 'Get English subtitles for video', 'Read transcript to find mentions of topic'. Use after list_caption_assets to get specific caption ID.

Input Schema

TableJSON Schema

Name	Required	Description	Default
`caption_asset_id`	Yes	Caption ID from list_caption_assets (format: '1_xyz789')

Implementation Reference

src/kaltura_mcp/tools/assets.py:97-189 (handler)

The core handler function that implements the logic for retrieving caption asset details from Kaltura API and downloading the caption text content via HTTP.

async def get_caption_content(
    manager: KalturaClientManager,
    caption_asset_id: str,
) -> str:
    """Get the actual text content of a caption asset."""

    if not CAPTION_AVAILABLE:
        return json.dumps(
            {
                "error": "Caption functionality is not available. The Caption plugin is not installed.",
                "captionAssetId": caption_asset_id,
            },
            indent=2,
        )

    client = manager.get_client()

    try:
        # Get caption asset details
        caption_asset = client.caption.captionAsset.get(caption_asset_id)

        # Get the caption content URL
        content_url = client.caption.captionAsset.getUrl(caption_asset_id)

        # Validate URL before making request
        if not content_url or not isinstance(content_url, str):
            download_error = "Invalid or missing caption URL"
            caption_text = None
        elif not content_url.startswith(("http://", "https://")):
            download_error = "Caption URL must use HTTP or HTTPS protocol"
            caption_text = None
        else:
            # Download the actual caption content
            caption_text = None
            download_error = None

            try:
                # Create a session for downloading
                session = requests.Session()

                # Set headers similar to reference implementation
                headers = {
                    "User-Agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) AppleWebKit/537.36"
                }

                # Download the caption content with timeout
                response = session.get(content_url, headers=headers, timeout=30)
                response.raise_for_status()

                # Get the text content
                caption_text = response.text

            except requests.exceptions.RequestException as e:
                download_error = f"Failed to download caption content: {str(e)}"
            except Exception as e:
                download_error = f"Error processing caption content: {str(e)}"

        result = {
            "captionAssetId": caption_asset_id,
            "entryId": caption_asset.entryId,
            "language": caption_asset.language.value
            if hasattr(caption_asset.language, "value")
            else str(caption_asset.language),
            "label": caption_asset.label,
            "format": caption_asset.format.value
            if hasattr(caption_asset.format, "value")
            else str(caption_asset.format),
            "contentUrl": content_url,
            "size": caption_asset.size,
            "accuracy": caption_asset.accuracy,
        }

        if caption_text is not None:
            result["captionText"] = caption_text
            result["textLength"] = len(caption_text)
            result["note"] = "Caption text content has been successfully downloaded and included."
        else:
            result["downloadError"] = download_error
            result[
                "note"
            ] = "Caption asset details retrieved but text content could not be downloaded. Use contentUrl for manual download."

        return json.dumps(result, indent=2)

    except Exception as e:
        return json.dumps(
            {
                "error": f"Failed to get caption content: {str(e)}",
                "captionAssetId": caption_asset_id,
            },
            indent=2,
        )

src/kaltura_mcp/server.py:448-461 (schema)

The input JSON schema and tool description defined in the list_tools() function for MCP tool registration.

types.Tool(
    name="get_caption_content",
    description="Get actual CAPTION TEXT or download captions file. USE WHEN: Reading video transcript, downloading subtitles, analyzing spoken content, creating accessible content. RETURNS: Full caption text and download URL. EXAMPLE: 'Get English subtitles for video', 'Read transcript to find mentions of topic'. Use after list_caption_assets to get specific caption ID.",
    inputSchema={
        "type": "object",
        "properties": {
            "caption_asset_id": {
                "type": "string",
                "description": "Caption ID from list_caption_assets (format: '1_xyz789')",
            },
        },
        "required": ["caption_asset_id"],
    },
),

src/kaltura_mcp/server.py:523-524 (registration)
Dispatch/execution point in the call_tool handler where get_caption_content is invoked based on tool name.
```
elif name == "get_caption_content":
    result = await get_caption_content(kaltura_manager, **arguments)
```
src/kaltura_mcp/server.py:36-36 (registration)
Import statement in server.py that brings in the get_caption_content function from tools module.
```
get_caption_content,
```
src/kaltura_mcp/tools/__init__.py:15-15 (helper)
Re-export of get_caption_content from assets.py in the tools package __init__.
```
get_caption_content,
```

Kaltura MCP Server