Skip to content

Script Generators

Prerequisites

Overview

Script Generators in Mosaico provide an automated way to create video shooting scripts from media collections. They're particularly useful for converting content like news articles into structured video scripts that can be used to generate complete video projects.

Script Generation System

The system consists of three main components:

  1. Script Generator Protocol: Defines the interface for script generators
  2. Shooting Script: Represents the structured output generated by the script generator
  3. Shot: Represents individual segments of the script

The ScriptGenerator Protocol

Key characteristics:

  • Runtime checkable protocol
  • Flexible input handling
  • Standardized output format
  • Extensible design
from mosaico.script_generators.protocol import ScriptGenerator
from mosaico.media import Media

@runtime_checkable
class ScriptGenerator(Protocol):
    def generate(self, media: Sequence[Media], **kwargs: Any) -> ShootingScript:
        """Generate a shooting script from media."""
        ...

Shooting Scripts

A ShootingScript represents a complete video script with multiple shots. The idea is to provide a structured format that can be used to generate video projects. The shooting script format was chosen to be simple and flexible, while still capturing the essential elements of a video script.

The main components of a shooting script are:

  • Title: The title of the script
  • Description: An optional description of the script content
  • Shots: Collection of shots that make up the script

These components provide a high-level overview of the video content and the individual segments that will be included in the final video.

Shots

Individual shots represent distinct segments in the script that can be used to create video projects. Each shot has the following properties:

  • Number: A unique identifier for the shot
  • Description: A brief description of the shot content
  • Start Time: The start time of the shot in the video
  • End Time: The end time of the shot in the video
  • Subtitle: Optional subtitles for the shot
  • Media References: References to the media used in the shot
  • Effects: Optional effects applied to the shot

Warning

Media references are not objects such as AssetReference, but rather simple strings that can be used to identify media objects in a media list. They should not be confused with actual media objects or AssetReference objects.

Using Script Generators

Basic Script Generation

# Create generator
generator = MyVideoScriptGenerator(
    context="News article content...",
    num_paragraphs=10
)

# Generate script from media
script = generator.generate(
    media=[
        image1_media,
        image2_media,
        video_media
    ]
)

Creating Video Projects

from mosaico.video.project import VideoProject

# Generate project from script
project = VideoProject.from_script_generator(
    script_generator=generator,
    media=media_files,
    speech_synthesizer=tts_engine,
    audio_transcriber=transcriber
)

Custom Script Generator

class CustomScriptGenerator:
    """Custom implementation of ScriptGenerator."""

    def generate(self,
                media: Sequence[Media],
                **kwargs: Any) -> ShootingScript:
        # Custom script generation logic
        shots = [
            Shot(
                number=1,
                description="Opening shot",
                start_time=0,
                end_time=5,
                subtitle="Welcome",
                media_references=[0],
                effects=["zoom_in"]
            )
        ]

        return ShootingScript(
            title="Custom Video",
            shots=shots
        )

Best Practices

Media Organization

  • Provide clear media descriptions
  • Order media logically
  • Include relevant metadata

Shot Management

  • Keep shots focused and concise
  • Ensure logical transitions
  • Match media to content

Working with Generated Scripts

Script Analysis

# Analyze generated script
print(f"Script duration: {script.duration}s")
print(f"Number of shots: {script.shot_count}")

for shot in script.shots:
    print(f"Shot {shot.number}: {shot.duration}s")
    print(f"Media used: {shot.media_references}")

Script Validation

def validate_script(script: ShootingScript) -> bool:
    """Validate script properties."""
    if script.duration > max_duration:
        return False

    if not all(shot.subtitle for shot in script.shots):
        return False

    return True

Media Reference Checking

def check_media_references(
    script: ShootingScript,
    media: Sequence[Media]
) -> bool:
    """Verify all media references are valid."""
    media_count = len(media)

    for shot in script.shots:
        if any(ref >= media_count for ref in shot.media_references):
            return False

    return True

Integration with Other Components

Speech Synthesis

# Generate speech for subtitles
speech_assets = speech_synthesizer.synthesize(
    [shot.subtitle for shot in script.shots]
)

Effect Application

# Apply effects from script
for shot in script.shots:
    effects = [create_effect(effect) for effect in shot.effects]
    # Apply to corresponding assets

Conclusion

Understanding script generators is crucial for automated video production in Mosaico. They provide a bridge between raw content and structured video projects, enabling efficient content transformation while maintaining creative control and quality standards.