davila7/claude-code-templates / cli-tool/components/skills/development/heygen-best-practices
heygen-best-practices
UnverifiedBest practices for HeyGen - AI avatar video creation API
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 2.5 KB |
| rules/assets.md | markdown | 8.1 KB |
| rules/authentication.md | markdown | 4.7 KB |
| rules/avatars.md | markdown | 18.3 KB |
| rules/backgrounds.md | markdown | 6.6 KB |
| rules/captions.md | markdown | 6.0 KB |
| rules/dimensions.md | markdown | 6.9 KB |
| rules/photo-avatars.md | markdown | 15.1 KB |
| rules/quota.md | markdown | 4.7 KB |
| rules/remotion-integration.md | markdown | 18.2 KB |
| rules/scripts.md | markdown | 10.0 KB |
| rules/streaming-avatars.md | markdown | 10.9 KB |
| rules/templates.md | markdown | 9.8 KB |
| rules/text-overlays.md | markdown | 6.9 KB |
| rules/video-agent.md | markdown | 8.9 KB |
| rules/video-generation.md | markdown | 20.9 KB |
| rules/video-status.md | markdown | 12.6 KB |
| rules/video-translation.md | markdown | 10.9 KB |
| rules/voices.md | markdown | 11.7 KB |
| rules/webhooks.md | markdown | 9.1 KB |
rules/captions.md
View on GitHub---
name: captions
description: Auto-generated captions and subtitle options for HeyGen videos
metadata:
tags: captions, subtitles, accessibility, srt
---
# Video Captions
HeyGen can automatically generate captions (subtitles) for your videos, improving accessibility and engagement.
## Enabling Captions
Captions can be enabled when generating a video:
```typescript
const videoConfig = {
video_inputs: [
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "normal",
},
voice: {
type: "text",
input_text: "Hello! This video will have automatic captions.",
voice_id: "1bd001e7e50f421d891986aad5158bc8",
},
},
],
// Caption settings (availability varies by plan)
caption: true,
};
```
## Caption Configuration Options
```typescript
interface CaptionConfig {
// Enable/disable captions
enabled: boolean;
// Caption style
style?: {
font_family?: string;
font_size?: number;
font_color?: string;
background_color?: string;
position?: "top" | "bottom";
};
// Language for caption generation
language?: string;
}
```
## Caption Styles
### Basic Captions
```typescript
const config = {
video_inputs: [...],
caption: true, // Enable with default styling
};
```
### Styled Captions
```typescript
const config = {
video_inputs: [...],
caption: {
enabled: true,
style: {
font_family: "Arial",
font_size: 32,
font_color: "#FFFFFF",
background_color: "rgba(0, 0, 0, 0.7)",
position: "bottom",
},
},
};
```
## Multi-Language Captions
For videos in different languages, captions are generated based on the voice language:
```typescript
// Spanish video with Spanish captions
const spanishConfig = {
video_inputs: [
{
character: {
type: "avatar",
avatar_id: "josh_lite3_20230714",
avatar_style: "normal",
},
voice: {
type: "text",
input_text: "¡Hola! Este video tendrá subtítulos en español.",
voice_id: "spanish_voice_id",
},
},
],
caption: true,
};
```
## Working with SRT Files
### Downloading SRT
After video generation, you may be able to download the SRT file:
```typescript
async function downloadSrt(videoId: string): Promise<string> {
const response = await fetch(
`https://api.heygen.com/v1/video/${videoId}/srt`,
{ headers: { "X-Api-Key": process.env.HEYGEN_API_KEY! } }
);
if (!response.ok) {
throw new Error("Failed to download SRT");
}
return response.text();
}
```
### SRT File Format
Standard SRT format:
```srt
1
00:00:00,000 --> 00:00:03,000
Hello! This video will have
2
00:00:03,000 --> 00:00:06,000
automatic captions generated.
3
00:00:06,000 --> 00:00:09,000
They sync with the audio.
```
### Using Custom SRT
For video translation, you can provide your own SRT:
```typescript
const translationConfig = {
input_video_id: "original_video_id",
output_languages: ["es-ES", "fr-FR"],
srt_key: "path/to/custom.srt", // Custom SRT file
srt_role: "input", // "input" or "output"
};
```
## Caption Positioning
### Bottom (Default)
Standard position for most videos:
```typescript
caption: {
enabled: true,
style: {
position: "bottom"
}
}
```
### Top
For videos where bottom space is occupied:
```typescript
caption: {
enabled: true,
style: {
position: "top"
}
}
```
## Accessibility Best Practices
1. **Always enable captions** - Improves accessibility for deaf/hard-of-hearing viewers
2. **Use high contrast** - White text on dark background or vice versa
3. **Readable font size** - At least 24px for standard video, larger for mobile
4. **Don't cover important content** - Position captions away from key visual elements
5. **Sync timing** - Ensure captions match audio timing accurately
## Caption Helper Functions
```typescript
interface CaptionStyle {
font_family: string;
font_size: number;
font_color: string;
background_color: string;
position: "top" | "bottom";
}
const captionPresets: Record<string, CaptionStyle> = {
default: {
font_family: "Arial",
font_size: 32,
font_color: "#FFFFFF",
background_color: "rgba(0, 0, 0, 0.7)",
position: "bottom",
},
minimal: {
font_family: "Arial",
font_size: 28,
font_color: "#FFFFFF",
background_color: "transparent",
position: "bottom",
},
bold: {
font_family: "Arial",
font_size: 36,
font_color: "#FFFFFF",
background_color: "rgba(0, 0, 0, 0.9)",
position: "bottom",
},
branded: {
font_family: "Roboto",
font_size: 30,
font_color: "#00D1FF",
background_color: "rgba(26, 26, 46, 0.9)",
position: "bottom",
},
};
function createCaptionConfig(preset: keyof typeof captionPresets) {
return {
enabled: true,
style: captionPresets[preset],
};
}
```
## Social Media Caption Considerations
### TikTok / Instagram Reels
- Position captions in center or upper portion
- Avoid bottom 20% (covered by UI elements)
- Use larger font sizes for mobile viewing
```typescript
const socialCaptions = {
enabled: true,
style: {
font_size: 42,
position: "top", // Avoid bottom UI elements
},
};
```
### YouTube
- Standard bottom captions work well
- YouTube also supports closed captions upload
### LinkedIn
- Captions highly recommended (many watch without sound)
- Professional styling preferred
## Limitations
- Caption styles may be limited depending on your subscription tier
- Some advanced caption features may require the web interface
- Multi-speaker caption detection may have limited availability
- Caption accuracy depends on audio quality and speech clarity
## Integration with Video Translation
When using video translation, captions are automatically handled:
```typescript
// Video translation includes caption generation
const translationConfig = {
input_video_id: "original_video_id",
output_languages: ["es-ES"],
// Captions generated in target language
};
```
See [video-translation.md](video-translation.md) for more details.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |