get_caption_content

Instructions

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,