Skip to content

Multimedia Documentation

Purpose

Standards and guidelines for creating multimedia content (videos, screenshots, animations) for AudioLab documentation.

Contents

Guidelines

  • video_production_guide.md - Tutorial video and screencast production
  • screenshot_standards.md - Screenshot capture and annotation
  • animation_tools.md - GIF creation and animation guidelines

Overview

Multimedia content enhances documentation by: - Demonstrating complex interactions visually - Showing real-time behavior (audio processing, UI feedback) - Providing step-by-step visual tutorials - Making documentation more engaging

Quick Reference

Screenshots

  • Format: PNG, 1920x1080+
  • Theme: VS Code Dark+ or One Dark Pro (consistent)
  • File Size: <500KB
  • Tool: ShareX (Windows), built-in (macOS)
  • Guide: screenshot_standards.md

Videos

  • Format: MP4 (H.264), 1920x1080, 60 FPS
  • Audio: 48kHz, AAC 192kbps
  • Captions: Required (SRT/VTT)
  • Tool: OBS Studio, DaVinci Resolve
  • Guide: video_production_guide.md

Animations/GIFs

  • Format: GIF or WebM
  • Resolution: 800x600 to 1200x900
  • Frame Rate: 15-30 FPS
  • File Size: <2MB (target), <5MB (max)
  • Tool: ScreenToGif, LICEcap
  • Guide: animation_tools.md

When to Use What

Content Type Best For Format Max Size
Screenshot Static UI, code, results PNG 500KB
Annotated Screenshot Explaining UI elements PNG 1MB
Short Animation Quick interactions (<10s) GIF 2MB
Tutorial Video Step-by-step workflows MP4 200MB/10min
Quick Tip Single feature demo MP4 or GIF 5MB
Diagram Architecture, flow SVG/PNG 200KB

File Organization

Directory Structure

var/media/
├── screenshots/
│   ├── raw/                # Unedited captures
│   ├── edited/             # Annotated/cropped
│   └── published/          # Optimized for web
├── videos/
│   ├── masters/            # High-quality source
│   ├── published/          # Compressed for web
│   └── captions/           # SRT/VTT files
├── animations/
│   ├── raw/                # Screen recordings
│   ├── edited/             # Optimized GIFs
│   └── published/          # Web-ready
└── assets/
    ├── templates/          # Intro/outro templates
    ├── music/              # Background music
    └── graphics/           # Logos, overlays

File Naming Convention

YYYY-MM-DD_content-description_version.ext

Examples:
2025-01-15_buffer-manager-ui.png
2025-01-15_gain-plugin-tutorial.mp4
2025-01-15_parameter-knob-animation.gif

Quality Standards

All Multimedia Content Must

  • Be clearly visible and readable
  • Not contain personal information (names, paths, keys)
  • Use consistent visual style (themes, colors)
  • Be optimized for web delivery
  • Have descriptive filenames
  • Include alt text (accessibility)

Screenshots Must

  • Be at least 1920x1080 resolution
  • Use PNG format
  • Be <500KB (optimized)
  • Show consistent theme (Dark+ or One Dark Pro)

Videos Must

  • Be 1080p or higher
  • Have clear audio (no distortion)
  • Include captions/subtitles
  • Have intro/outro (if >2 min)
  • Be <200MB per 10 minutes

Animations Must

  • Be <5MB file size
  • Demonstrate clear action (not cluttered)
  • Loop cleanly (if looping)
  • Be 15-30 FPS

Tools Setup

Essential (Free)

# Screenshot tools
winget install ShareX        # Windows

# Video tools
winget install OBSProject.OBSStudio
winget install Audacity.Audacity

# Optimization
winget install ImageMagick.ImageMagick  # Image processing
choco install ffmpeg                     # Video processing

Optional (Paid)

  • Snagit ($50): Advanced screenshot annotation
  • Camtasia ($299): All-in-one video editing
  • Adobe Premiere Pro ($20/mo): Professional video editing

Online Tools

Workflow Examples

Creating a Screenshot

  1. Set up environment (close apps, use consistent theme)
  2. Capture with ShareX (PrintScreen)
  3. Crop and annotate if needed
  4. Optimize with TinyPNG or ImageOptim
  5. Save to var/media/screenshots/published/
  6. Reference in documentation

Creating a Tutorial Video

  1. Write script/outline
  2. Prepare demo project
  3. Record with OBS Studio (1080p60, 10Mbps)
  4. Edit in DaVinci Resolve (trim, add intro/outro)
  5. Export MP4 H.264 (8-12Mbps)
  6. Generate captions (YouTube auto + corrections)
  7. Upload to hosting (YouTube/Vimeo)
  8. Embed in documentation

Creating an Animation

  1. Set up screen capture area (800x600)
  2. Record with ScreenToGif (20 FPS)
  3. Edit: trim frames, reduce colors to 128
  4. Apply lossy compression (quality 80)
  5. Verify <2MB file size
  6. Save to var/media/animations/published/
  7. Embed in documentation

Embedding in Documentation

Screenshot (Markdown)

![Buffer Manager UI](../media/screenshots/buffer-manager-ui.png)

Video (Embed)

## Tutorial: Building a Gain Plugin

<iframe width="800" height="450" src="https://www.youtube.com/embed/VIDEO_ID" frameborder="0" allowfullscreen></iframe>

[Download MP4](../media/videos/gain-plugin-tutorial.mp4) (50MB)

Animation (GIF)

![Parameter knob interaction](../media/animations/parameter-knob.gif)
*Drag the knob to adjust frequency (500Hz - 20kHz)*

Accessibility

Alt Text (Required)

All images must have descriptive alt text: 

![Screenshot of the AudioBuffer class hierarchy showing DynamicBuffer and StaticBuffer inheriting from AudioBuffer base class](class-hierarchy.png)

Captions (Required for Videos)

All videos must include captions (SRT or VTT): 

1
00:00:00,000 --> 00:00:03,000
Welcome to AudioLab. Today we'll build a simple gain plugin.

2
00:00:03,500 --> 00:00:07,000
First, create a new project using the AudioLab template.

Provide text transcripts for longer videos: 

## Video Transcript

[00:00] Welcome to AudioLab...
[00:15] First, create a new project...

Optimization Tips

Reduce Screenshot Size

# Using ImageMagick
magick convert input.png -quality 90 -resize 1920x1080 output.png

# Using optipng
optipng -o5 screenshot.png

Reduce Video Size

# FFmpeg: Compress video
ffmpeg -i input.mp4 -c:v libx264 -crf 23 -preset medium -c:a aac -b:a 192k output.mp4

Reduce GIF Size

# Using gifsicle
gifsicle -O3 --lossy=80 --colors 128 input.gif -o output.gif

Hosting Options

Self-Hosted

  • Store in var/media/ (not in git - use Git LFS)
  • Serve via web server or CDN
  • Pros: Full control, no external dependencies
  • Cons: Storage/bandwidth costs

External Hosting

  • YouTube: Videos (free, unlimited, good player)
  • Vimeo: Videos (better quality control, paid)
  • GitHub Releases: Large files (2GB limit per file)
  • Imgur: Screenshots/GIFs (free, simple)

Git LFS (Large File Storage)

# Install Git LFS
git lfs install

# Track multimedia files
git lfs track "var/media/**/*.mp4"
git lfs track "var/media/**/*.gif"
git lfs track "var/media/**/*.png"

# Commit .gitattributes
git add .gitattributes
git commit -m "docs: configure Git LFS for media files"

Maintenance

Regular Tasks

  • Review and update outdated screenshots (quarterly)
  • Re-record videos when UI changes significantly
  • Optimize new media files before committing
  • Check for broken video embeds (monthly)
  • Archive old media (don't delete, move to archive/)

Versioning

Keep old versions when updating: 

buffer-manager-ui_v1.png  (AudioLab 1.0)
buffer-manager-ui_v2.png  (AudioLab 2.0)

Reference specific version in docs: 

![Buffer Manager (v2.0)](buffer-manager-ui_v2.png)

References

Guides

External Resources

Support

For questions about multimedia content creation: - Review appropriate guide (video, screenshot, or animation) - Check examples in var/media/examples/ - Consult external tool documentation