Auto-Attach Related Assets

The Auto-Attach Related Assets feature automatically discovers and attaches supplementary files (thumbnails, preview images, subtitles, metadata) to primary assets based on file naming conventions. When files are uploaded to the same folder with matching names, they are automatically linked without manual intervention.

How It Works

When an asset is uploaded, the system checks for related files in the same folder that match configured naming patterns. If matches are found, they are automatically attached to the primary asset with the appropriate metadata type.

Example:

video.mp4                    → Primary asset
video.mp4.thumbnailimage     → Auto-attached as ThumbnailImage
video.mp4.previewimage       → Auto-attached as PreviewImage
video.mp4.en.vtt             → Auto-attached as TranscribeVtt (English)
video.mp4.es.vtt             → Auto-attached as TranscribeVttTranslation (Spanish)
video.mp4.json               → Auto-attached as AssociatedAsset

Default Configuration

The system includes default auto-attach rules that work out of the box:

Wildcard Matching

By default, auto-attach rules apply to all asset types (videos, images, documents, etc.). This means you can attach thumbnails to any file type without configuring specific extensions.

Naming Patterns

The system supports two naming patterns for related assets:

1. Double Extension Pattern (Recommended)

<primary-filename>.<primary-extension>.<related-extension>

Examples:

• video.mp4.thumbnailimage → Thumbnail for video.mp4
• document.pdf.previewimage → Preview for document.pdf
• audio.mp3.json → Metadata for audio.mp3

2. Base Name Pattern

<primary-filename-without-extension>.<related-extension>

Examples:

• video.thumbnailimage → Thumbnail for video.mp4
• document.previewimage → Preview for document.pdf

Note: The double extension pattern is recommended as it's more explicit and avoids ambiguity.

Subtitle Language Detection

For subtitle files (.vtt and .srt), the system automatically detects the language from the filename and sets it appropriately.

Language Code Patterns

Insert a language code between the primary filename and the subtitle extension:

<primary-filename>.<language-code>.vtt
<primary-filename>.<language-code>.srt

Supported language code formats:

• ISO 639-1 (2-letter): en, es, fr, de, ja, etc.
• ISO 639-2 (3-letter): eng, spa, fra, deu, jpn, etc.
• ISO 639-3 (5-letter with region): en-US, en-GB, es-MX, fr-CA, etc.

Examples

video.mp4.en.vtt             → English subtitles (TranscribeVtt)
video.mp4.es.vtt             → Spanish subtitles (TranscribeVttTranslation)
video.mp4.en-US.srt          → English (US) subtitles (TranscribeSrt)
video.mp4.fr-CA.vtt          → French (Canadian) subtitles (TranscribeVttTranslation)

Primary vs. Translation Subtitles

The system automatically determines whether a subtitle is a primary transcript or a translation:

• If the subtitle language matches the primary asset's language → TranscribeVtt (primary transcript)
• If the subtitle language differs from the primary asset's language → TranscribeVttTranslation (translation)

Example:

Primary asset: video.mp4 (language: English)
  video.mp4.en.vtt     → TranscribeVtt (primary)
  video.mp4.es.vtt     → TranscribeVttTranslation (translation)
  video.mp4.fr.vtt     → TranscribeVttTranslation (translation)

Bidirectional Attachment

Auto-attach works in both directions:

1. Primary asset uploaded first → When a related asset is uploaded later, it's automatically attached
2. Related asset uploaded first → When the primary asset is uploaded later, the related asset is automatically attached

This ensures files can be uploaded in any order and still be linked correctly.

Configuration

Auto-attach behavior is configured via AWS SSM Parameter Store at:

application/autoAttachRelatedAssetsSettings

Configuration Structure

{
  "autoAttachRelatedAssets": [
    {
      "assetExtensions": null,
      "relatedAssetExtensions": [
        {
          "extension": ".thumbnailimage",
          "title": "Thumbnail Image",
          "relatedMetadataType": "ThumbnailImage"
        },
        {
          "extension": ".previewimage",
          "title": "Preview Image",
          "relatedMetadataType": "PreviewImage"
        },
        {
          "extension": ".vtt",
          "title": "Subtitles",
          "relatedMetadataType": "TranscribeVtt"
        },
        {
          "extension": ".srt",
          "title": "Subtitles",
          "relatedMetadataType": "TranscribeSrt"
        },
        {
          "extension": ".json",
          "title": "Metadata"
        }
      ]
    }
  ]
}

Configuration Properties

Custom Configuration Example

To restrict auto-attach to specific file types:

{
  "autoAttachRelatedAssets": [
    {
      "assetExtensions": [".mp4", ".mov", ".avi"],
      "relatedAssetExtensions": [
        {
          "extension": ".thumbnailimage",
          "title": "Thumbnail",
          "relatedMetadataType": "ThumbnailImage"
        }
      ]
    },
    {
      "assetExtensions": [".pdf", ".docx"],
      "relatedAssetExtensions": [
        {
          "extension": ".previewimage",
          "title": "Preview",
          "relatedMetadataType": "PreviewImage"
        }
      ]
    }
  ]
}

This configuration:

• Attaches .thumbnailimage files only to video assets (.mp4, .mov, .avi)
• Attaches .previewimage files only to document assets (.pdf, .docx)

Use Cases

1. Video Thumbnails and Previews

video.mp4
video.mp4.thumbnailimage     (small thumbnail for lists)
video.mp4.previewimage       (large poster for detail view)

2. Multi-Language Subtitles

video.mp4
video.mp4.en.vtt             (English)
video.mp4.es.vtt             (Spanish)
video.mp4.fr.vtt             (French)
video.mp4.de.vtt             (German)

3. Document Previews

report.pdf
report.pdf.previewimage      (preview image of first page)
report.pdf.json              (extracted metadata)

4. Audio with Metadata

podcast.mp3
podcast.mp3.thumbnailimage   (episode artwork)
podcast.mp3.json             (episode metadata)
podcast.mp3.en.vtt           (transcript)

Best Practices

1. Use Consistent Naming - Stick to the double extension pattern for clarity
2. Include Language Codes - Always specify language codes for subtitle files
3. Test in Development - Verify auto-attach behavior before deploying to production
4. Monitor Logs - Check asset processing logs to ensure files are being attached correctly
5. Use Metadata Types - Specify relatedMetadataType to ensure proper categorization

Troubleshooting

Related Asset Not Attaching

Possible causes:

• File extension doesn't match configuration
• Files are in different folders
• Asset hasn't finished processing yet

Solution:

• Verify file naming matches the pattern exactly (case-insensitive)
• Ensure both files are in the same folder
• Wait for asset processing to complete

Language Not Detected

Possible causes:

• Language code not recognized
• Language code in wrong position in filename

Solution:

• Use standard ISO language codes (en, es, en-US, etc.)
• Ensure language code is between filename and extension: video.mp4.en.vtt

Wrong Metadata Type Assigned

Possible causes:

• Configuration doesn't specify relatedMetadataType
• Multiple rules matching the same extension

Solution:

• Add relatedMetadataType to configuration
• Review configuration for conflicting rules

Related Documentation

• Uploading SRT Subtitle Files
• Asset Processor Overview
• Metadata Folders and Structures
• Asset Management API