Veedeo API V3 Font Reference

Complete Font Support Guide Last Updated: September 18, 2025 Version: 3.0 (with Source Han Sans Support)

Overview

The Veedeo API V3 provides a curated set of professional fonts optimized for video subtitle rendering. All fonts are pre-installed in our rendering containers to ensure consistent output across all environments.

Supported Font Families

English/Latin Fonts

Liberation Font Family (Complete Collection)

Based on metrics-compatible alternatives to Arial, Times New Roman, and Courier.

DejaVu Font Family (Complete Collection)

High-quality fonts with excellent Unicode support and extensive style variants.

Chinese/CJK Fonts

Noto CJK Font Family (Complete Collection)

Professional Chinese fonts optimized for video rendering with multiple weights.

Source Han Sans Font Family (Adobe CJK - Premium Quality)

Professional sans-serif fonts from Adobe for superior CJK rendering quality.

Font Aliases

For convenience, the following aliases are available:

Legacy Aliases

Backward compatibility aliases for common font requests:

Usage Examples

Basic Font Selection

{
  "properties": {
    "font_family": "liberation-sans",
    "font_size": 24,
    "color": "#FFFFFF"
  }
}

Bold Font Usage

{
  "properties": {
    "font_family": "dejavu-sans-bold",
    "font_size": 28,
    "color": "#FFFFFF"
  }
}

Chinese Text

{
  "properties": {
    "font_family": "sourcehan-sans-sc",
    "font_size": 26,
    "color": "#FFFFFF"
  }
}

Source Han Sans (Premium Chinese)

{
  "properties": {
    "font_family": "sourcehan-sans-sc-bold",
    "font_size": 28,
    "color": "#FFFFFF"
  }
}

Using Aliases

{
  "properties": {
    "font_family": "sans",
    "font_size": 22,
    "color": "#FFFFFF"
  }
}

Legacy Compatibility

{
  "properties": {
    "font_family": "arial",
    "font_size": 24,
    "color": "#FFFFFF"
  }
}

Subtitle Preset Font Usage

Built-in Presets

Each preset uses carefully selected fonts optimized for their use case:

Preset Usage

{
  "properties": {
    "preset": "netflix",
    "font_size": 24
  }
}

Custom Styling with Preset Base

{
  "properties": {
    "preset": "professional",
    "font_family": "dejavu-serif-bold",
    "font_size": 28,
    "color": "#F0F0F0"
  }
}

Chinese Platform Presets

{
  "properties": {
    "preset": "douyin",
    "font_size": 26
  }
}

{
  "properties": {
    "preset": "xiaohongshu",
    "font_family": "sourcehan-sans-sc-bold"
  }
}

{
  "properties": {
    "preset": "wechat-video",
    "color": "#F0F0F0"
  }
}

Font Validation

Strict Font Policy

The API enforces a strict font policy:

• Only fonts from the approved list are supported
• No system font fallbacks are used
• Invalid font names will cause render errors

Error Handling

If you specify an unsupported font, you'll receive an error like:

{
  "error": {
    "code": "FONT_NOT_SUPPORTED",
    "message": "STRICT FONT POLICY: Font 'Comic Sans' not found in fonts/ directory. Available fonts: liberation-sans, dejavu-sans, ..."
  }
}

Validation Function

Before submitting requests, you can validate fonts using this logic:

const supportedFonts = [
  // Liberation fonts (all variants)
  'liberation-sans', 'liberation-sans-bold', 'liberation-sans-italic', 'liberation-sans-bold-italic',
  'liberation-serif', 'liberation-serif-bold', 'liberation-serif-italic', 'liberation-serif-bold-italic',
  'liberation-mono', 'liberation-mono-bold', 'liberation-mono-italic', 'liberation-mono-bold-italic',

  // DejaVu fonts (all variants)
  'dejavu-sans', 'dejavu-sans-bold', 'dejavu-sans-oblique', 'dejavu-sans-bold-oblique', 'dejavu-sans-extralight',
  'dejavu-sans-condensed', 'dejavu-sans-condensed-bold', 'dejavu-sans-condensed-oblique', 'dejavu-sans-condensed-bold-oblique',
  'dejavu-serif', 'dejavu-serif-bold', 'dejavu-serif-italic', 'dejavu-serif-bold-italic',
  'dejavu-serif-condensed', 'dejavu-serif-condensed-bold', 'dejavu-serif-condensed-italic', 'dejavu-serif-condensed-bold-italic',
  'dejavu-mono', 'dejavu-mono-bold', 'dejavu-mono-oblique', 'dejavu-mono-bold-oblique', 'dejavu-math',

  // Noto CJK fonts (all variants)
  'noto-serif-sc', 'noto-serif-sc-bold', 'noto-serif-sc-light',
  'noto-serif-tc', 'noto-serif-tc-bold', 'noto-serif-tc-light',

  // Source Han Sans fonts (all variants)
  'sourcehan-sans-sc', 'sourcehan-sans-sc-bold', 'sourcehan-sans-sc-light',
  'sourcehan-sans-tc', 'sourcehan-sans-tc-bold', 'sourcehan-sans-tc-light',

  // Aliases
  'sans', 'serif', 'mono', 'monospace', 'chinese', 'chinese-sans', 'chinese-serif', 'chinese-tc', 'chinese-tc-sans',
  'arial', 'arial-black', 'times', 'times-new-roman', 'courier', 'courier-new', 'helvetica', 'georgia'
];

function isValidFont(fontName) {
  const normalized = fontName.toLowerCase().replace(/\s+/g, '-');
  return supportedFonts.includes(normalized);
}

Best Practices

Font Selection Guidelines

1. For English content: Use liberation-sans or dejavu-sans
2. For Chinese content: Use sourcehan-sans-sc (Simplified) or sourcehan-sans-tc (Traditional) for sans-serif, noto-serif-sc/noto-serif-tc for serif
3. For professional content: Use liberation-serif or dejavu-serif
4. For emphasis: Use bold variants (-bold suffix)
5. For technical content: Use liberation-mono or dejavu-mono

Performance Considerations

• All fonts are pre-loaded in rendering containers
• Font switching within a video has no performance impact
• Bold fonts may appear slightly larger at the same font size

Accessibility

• Use high contrast ratios (white text on dark backgrounds)
• Minimum font size recommendation: 18px for readability
• Serif fonts may be more readable for longer text content

Language-Specific Recommendations

English/Latin Text

• Primary: liberation-sans, dejavu-sans
• Professional: liberation-serif, dejavu-serif
• Technical: liberation-mono, dejavu-mono

Chinese Text

• Simplified Chinese Sans-serif: sourcehan-sans-sc (recommended), sourcehan-sans-sc-bold
• Simplified Chinese Serif: noto-serif-sc, noto-serif-sc-bold
• Traditional Chinese Sans-serif: sourcehan-sans-tc, sourcehan-sans-tc-bold
• Traditional Chinese Serif: noto-serif-tc, noto-serif-tc-bold
• Mixed content: Use chinese alias for automatic selection (now defaults to Source Han Sans)

Migration Guide

From Previous Versions

If you're migrating from older API versions:

1. Replace custom font names with supported fonts:

   - "font_family": "Arial"
   + "font_family": "liberation-sans"
   

2. Use aliases for convenience:

   - "font_family": "Times New Roman"
   + "font_family": "times"
   

3. Update Chinese font references:

   - "font_family": "SimSun"
   + "font_family": "sourcehan-sans-sc"
   

4. Upgrade to premium Chinese fonts:

   - "font_family": "noto-serif-sc"
   + "font_family": "sourcehan-sans-sc"
   

Testing Font Changes

1. Start with safe defaults: Use liberation-sans for testing
2. Test with actual content: Ensure Chinese characters render correctly with Source Han Sans
3. Verify on mobile: Check readability at different resolutions
4. Use presets: Leverage built-in presets for consistent styling
5. Compare quality: Test Source Han Sans vs Noto CJK for your use case

Troubleshooting

Common Issues

Font Not Found Error

Solution: Check font name against supported list, use exact keys

Chinese Characters Not Displaying

Solution: Use 'sourcehan-sans-sc' or 'sourcehan-sans-tc' for best CJK rendering
Alternative: Use 'noto-serif-sc' or 'noto-serif-tc' for serif style

Text Appears Too Small/Large

Solution: Adjust font_size, consider font family differences

Bold Text Not Working

Solution: Use explicit bold variants (e.g., 'dejavu-sans-bold')

Getting Help

For font-related issues:

1. Check this reference document
2. Validate font names against supported list
3. Test with basic presets first
4. Contact support with specific font requirements

Last Updated: September 18, 2025 API Version: 3.0 (with Source Han Sans Support) Documentation Version: 1.1

For technical support or font requests, contact support@veedeo.dev.