ÃÛ¶¹ÊÓƵ

Documentation

Programmatically add VTT captions in AEMaaCS Dynamic Media

Last update: Wed Jun 18 2025 00:00:00 GMT+0000 (Coordinated Universal Time)

ÃÛ¶¹ÊÓƵ Experience Manager as a Cloud Service (AEMaaCS) doesn’t offer a public API to programmatically upload VTT caption files to Dynamic Media. To resolve this, upload the video asset, create a subassets folder, upload VTT files, and post metadata using internal endpoints like S7AudioCaptionsMetadataServlet.

Description description

Environment

ÃÛ¶¹ÊÓƵ Experience Manager as a Cloud Service (AEMaaCS) - Assets, Dynamic Media

Issue/Symptoms

AEMaaCS doesn’t provide a public API to programmatically upload and associate VTT caption files with video assets in Dynamic Media. Captions must be uploaded manually through the UI, which prevents automation of caption management for video assets.

Resolution resolution

The following steps provide an overview of how to programmatically upload and associate VTT caption files with video assets using internal implementation methods:

  1. Upload the primary video file to AEMaaCS DAM (Digital Asset Management) and confirm it processes successfully. Example path: /content/dam/test/sample.mp4.

  2. Check if the subassets folder exists under the video asset by sending a GET request to /content/dam/test/sample.mp4/subassets.json.

    If it returns a 404 error, create the folder using a POST request with jcr:primaryType=nt:folder.

    Example:

    code language-none 
    curl -u admin:admin \
-F "jcr:primaryType=nt:folder" \
http://localhost:4502/content/dam/test/sample.mp4/subassets\

  3. Upload audio files such asaudio1.mp3 and caption files such as english.vtt into the subassets folder.

    Example:

    Caption: /content/dam/test/sample.mp4/subassets/chinese.vtt

    Audio: /content/dam/test/sample.mp4/subassets/audio1.mp3

    You can use the aem-upload library for uploading: .

  4. POST metadata for each audio file using the S7AudioCaptionsMetadataServlet:

    code language-none 
    curl -u user:password \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [ {
      "filename": "chinese.vtt",
      "language": "Chinese",
      "languageCode": "zho",
      "role": "subtitle",
      "label": "ch-subtitle",
      "isDefault": false
    }]
  }' \
  http://localhost:4502/content/dam/test/sample.mp4.audiocaptionsmetadata.json

  5. POST metadata for each caption file:

    code language-none 
    curl -u user:password \
  -H "Content-Type: application/json" \
  -d '{
    "payload": [ {
      "filename": "chinese.vtt",
      "language": "Chinese",
      "languageCode": "zho",
      "role": "subtitle",
      "label": "ch-subtitle",
      "isDefault": false
    }]
  }' \
  http://localhost:4502/content/dam/test/sample.mp4.audiocaptionsmetadata.json

  6. Retrieve metadata using GET requests to the .audiocaptionsmetadata.json endpoint to confirm the caption and audio files are correctly associated.

    Examples:

    • For captions: curl -u user:password "http://localhost:4502/content/dam/test/sample.mp4.audiocaptionsmetadata.json?type=vtt&offset=0"
    • For audio: curl -u user:password "http://localhost:4502/content/dam/test/sample.mp4.audiocaptionsmetadata.json?type=audio&offset=0"

Additional Notes

  • This approach relies on inspecting the HTTP requests made from the client side to AEM using browser developer tools such as Chrome’s Network tab.
  • This is an internal implementation and is not a supported public API.
  • This method is intended for exploration and testing based on specific use cases and requirements.
recommendation-more-help
3d58f420-19b5-47a0-a122-5c9dab55ec7f