+ Bases: BaseModel
Represents an asset used in a scene.
+ + + + +instance-attribute
+
+
+asset_id: str
+The ID of the asset.
+instance-attribute
+
+
+asset_type: AssetType
+The refered asset type.
+class-attribute
+ instance-attribute
+
+
+asset_params: AssetParams | None = None
+The asset reference params.
+class-attribute
+ instance-attribute
+
+
+start_time: NonNegativeFloat = 0
+The start time of the asset in seconds.
+class-attribute
+ instance-attribute
+
+
+end_time: NonNegativeFloat = 0
+The end time of the asset in seconds.
+class-attribute
+ instance-attribute
+
+
+effects: list[VideoEffect] = Field(default_factory=list)
+The effects to apply to the asset.
+property
+
+
+duration: float
+The duration of the asset in seconds.
+classmethod
+
+
+from_asset(
+ asset: Asset,
+ *,
+ asset_params: AssetParams | None = None,
+ start_time: float | None = None,
+ end_time: float | None = None,
+ effects: Sequence[VideoEffect] | None = None
+) -> AssetReference
+Create an asset reference from an asset.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset |
+
+ Asset
+ |
+
+
+
+ The asset to reference. + |
+ + required + | +
asset_params |
+
+ AssetParams | None
+ |
+
+
+
+ The asset params. + |
+
+ None
+ |
+
start_time |
+
+ float | None
+ |
+
+
+
+ The start time of the asset in seconds. + |
+
+ None
+ |
+
end_time |
+
+ float | None
+ |
+
+
+
+ The end time of the asset in seconds. + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.pyclassmethod
+
+
+from_dict(data: Mapping[str, Any]) -> AssetReference
+Create an asset reference from a dictionary.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ Mapping[str, Any]
+ |
+
+
+
+ The dictionary data. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.pywith_params(params: AssetParams) -> AssetReference
+Add scene params to the asset reference.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
params |
+
+ AssetParams
+ |
+
+
+
+ The scene params to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.pywith_start_time(start_time: float) -> AssetReference
+Add a start time to the asset reference.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
start_time |
+
+ float
+ |
+
+
+
+ The start time to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.pywith_end_time(end_time: float) -> AssetReference
+Add an end time to the asset reference.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
end_time |
+
+ float
+ |
+
+
+
+ The end time to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.pywith_effects(effects: Sequence[Effect]) -> AssetReference
+Add effects to the asset reference.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
effects |
+
+ Sequence[Effect]
+ |
+
+
+
+ The effects to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetReference
+ |
+
+
+
+ The asset reference. + |
+
src/mosaico/assets/reference.py
+ Bases: BaseModel
Represents the parameters for an Audio assets.
+ + + + +class-attribute
+ instance-attribute
+
+
+The volume of the audio assets.
+
+ Bases: BaseAsset[AudioAssetParams]
Represents an Audio asset with various properties.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['audio'] = 'audio'
+The type of the asset. Defaults to "audio".
+class-attribute
+ instance-attribute
+
+
+params: AudioAssetParams = Field(
+ default_factory=AudioAssetParams
+)
+The parameters for the asset.
+instance-attribute
+
+
+duration: PositiveFloat
+The duration of the audio asset.
+instance-attribute
+
+
+sample_rate: PositiveFloat
+The sample rate of the audio asset.
+instance-attribute
+
+
+sample_width: NonNegativeInt
+The sample width of the audio asset.
+instance-attribute
+
+
+channels: int
+The number of channels in the audio asset.
+classmethod
+
+
+from_data(
+ data: str | bytes,
+ *,
+ path: PathLike | None = None,
+ metadata: dict | None = None,
+ mime_type: str | None = None,
+ **kwargs: Any
+) -> Self
+Creates an audio asset from data.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ str | bytes
+ |
+
+
+
+ The data of the assets. + |
+ + required + | +
path |
+
+ PathLike | None
+ |
+
+
+
+ The path to the file. + |
+
+ None
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the assets. + |
+
+ None
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the assets. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The assets. + |
+
src/mosaico/assets/audio.pyclassmethod
+
+
+from_path(
+ path: PathLike,
+ *,
+ encoding: str = "utf-8",
+ mime_type: str | None = None,
+ guess_mime_type: bool = True,
+ metadata: dict | None = None,
+ **kwargs: Any
+) -> Self
+Creates an audio asset from a file path.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
path |
+
+ PathLike
+ |
+
+
+
+ The path to the file. + |
+ + required + | +
encoding |
+
+ str
+ |
+
+
+
+ The encoding of the file. + |
+
+ 'utf-8'
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the assets. + |
+
+ None
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the assets. + |
+
+ None
+ |
+
guess_mime_type |
+
+ bool
+ |
+
+
+
+ Whether to guess the MIME type. + |
+
+ True
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The assets. + |
+
src/mosaico/assets/audio.pyslice(start_time: float, end_time: float) -> AudioAsset
+Slices the audio asset.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
start_time |
+
+ float
+ |
+
+
+
+ The start time in seconds. + |
+ + required + | +
end_time |
+
+ float
+ |
+
+
+
+ The end time in seconds. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AudioAsset
+ |
+
+
+
+ The sliced audio asset. + |
+
src/mosaico/assets/audio.py
+ Bases: BaseModel
Represents the parameters for an image assets.
+ + + + +class-attribute
+ instance-attribute
+
+
+position: Position = Field(default_factory=AbsolutePosition)
+The positioning of the text assets in the video.
+class-attribute
+ instance-attribute
+
+
+z_index: int = -1
+The z-index of the assets.
+class-attribute
+ instance-attribute
+
+
+The crop range for the image assets.
+class-attribute
+ instance-attribute
+
+
+as_background: bool = True
+Whether the image should be used as a background.
+
+ Bases: BaseAsset[ImageAssetParams]
Represents an image assets with various properties.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['image'] = 'image'
+The type of the assets. Defaults to "image".
+class-attribute
+ instance-attribute
+
+
+params: ImageAssetParams = Field(
+ default_factory=ImageAssetParams
+)
+The parameters for the assets.
+instance-attribute
+
+
+width: NonNegativeInt
+The width of the image.
+instance-attribute
+
+
+height: NonNegativeInt
+The height of the image.
+classmethod
+
+
+from_data(
+ data: str | bytes,
+ *,
+ path: PathLike | None = None,
+ metadata: dict | None = None,
+ mime_type: str | None = None,
+ **kwargs: Any
+) -> Self
+Creates an image asset from data.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ str | bytes
+ |
+
+
+
+ The data of the assets. + |
+ + required + | +
path |
+
+ PathLike | None
+ |
+
+
+
+ The path to the file. + |
+
+ None
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the assets. + |
+
+ None
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the assets. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The assets. + |
+
src/mosaico/assets/image.pyclassmethod
+
+
+from_path(
+ path: PathLike,
+ *,
+ encoding: str = "utf-8",
+ mime_type: str | None = None,
+ guess_mime_type: bool = True,
+ metadata: dict | None = None,
+ **kwargs: Any
+) -> Self
+Creates an image asset from a file path.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
path |
+
+ PathLike
+ |
+
+
+
+ The path to the file. + |
+ + required + | +
encoding |
+
+ str
+ |
+
+
+
+ The encoding of the file. + |
+
+ 'utf-8'
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the assets. + |
+
+ None
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the assets. + |
+
+ None
+ |
+
guess_mime_type |
+
+ bool
+ |
+
+
+
+ Whether to guess the MIME type. + |
+
+ True
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The assets. + |
+
src/mosaico/assets/image.pyRepresents an assets with various properties.
+ + + + +instance-attribute
+
+
+The parameters for the assets.
+classmethod
+
+
+classmethod
+
+
+classmethod
+
+
+validate_params(params: Any) -> T
+Validates the parameters for the assets.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
params |
+
+ Any
+ |
+
+
+
+ The parameters to validate. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ T
+ |
+
+
+
+ The validated parameters. + |
+
src/mosaico/assets/base.pyReturns a new assets with the specified parameters.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
params |
+
+ T | dict[str, Any]
+ |
+
+
+
+ The parameters to update. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ A new assets with the specified parameters. + |
+
src/mosaico/assets/base.pymodule-attribute
+
+
+AssetType = Literal[
+ "video", "image", "audio", "text", "subtitle"
+]
+An enumeration of the different types of assets that can be held in an assets.
+module-attribute
+
+
+Asset = AudioAsset | ImageAsset | TextAsset | SubtitleAsset
+Represents an assets with various properties.
+module-attribute
+
+
+AssetParams = (
+ AudioAssetParams | ImageAssetParams | TextAssetParams
+)
+Represents the parameters of an assets.
+create_asset(
+ asset_type: AssetType,
+ id: str | None = None,
+ data: str | bytes | None = None,
+ path: PathLike | None = None,
+ metadata: dict[str, Any] | None = None,
+ params: AssetParams | dict[str, Any] | None = None,
+ **kwargs: Any
+) -> Asset
+Create an asset from the given asset type.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_type |
+
+ AssetType
+ |
+
+
+
+ The asset type. + |
+ + required + | +
id |
+
+ str | None
+ |
+
+
+
+ The asset ID. + |
+
+ None
+ |
+
data |
+
+ str | bytes | None
+ |
+
+
+
+ The asset data. + |
+
+ None
+ |
+
path |
+
+ PathLike | None
+ |
+
+
+
+ The asset path. + |
+
+ None
+ |
+
metadata |
+
+ dict[str, Any] | None
+ |
+
+
+
+ The asset metadata. ;param params: The asset parameters. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Asset
+ |
+
+
+
+ The asset. + |
+
src/mosaico/assets/factory.pyget_asset_params_class(
+ asset_type: AssetType,
+) -> type[AssetParams]
+Get the asset parameters class for the given asset type.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_type |
+
+ AssetType
+ |
+
+
+
+ The asset type. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ type[AssetParams]
+ |
+
+
+
+ The asset parameters class. + |
+
src/mosaico/assets/factory.pyConvert a media object to an asset.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
media |
+
+ Media
+ |
+
+
+
+ The media object to convert. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Asset
+ |
+
+
+
+ The asset object. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If the media object does not have a MIME type or the MIME type is unsupported. + |
+
src/mosaico/assets/utils.pyGuess the asset type from a MIME type.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
mime_type |
+
+ str
+ |
+
+
+
+ The MIME type to guess the asset type from. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AssetType
+ |
+
+
+
+ The asset type. + |
+
src/mosaico/assets/utils.pyCheck if the user provided all required keys.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ dict
+ |
+
+
+
+ The data to check. + |
+ + required + | +
required_keys |
+
+ Sequence[str]
+ |
+
+
+
+ The required keys. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ Whether the user provided all required keys. + |
+
src/mosaico/assets/utils.py
+ Bases: BaseTextAsset
Represents a subtitles assets.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['subtitle'] = 'subtitle'
+The type of the assets. Defaults to "subtitle".
+class-attribute
+ instance-attribute
+
+
+params: TextAssetParams = Field(
+ default_factory=lambda: TextAssetParams(
+ position=RegionPosition(x="center", y="bottom"),
+ font_color=Color("white"),
+ font_size=45,
+ stroke_width=1,
+ align="center",
+ shadow_blur=10,
+ shadow_angle=135,
+ shadow_opacity=0.5,
+ shadow_distance=5,
+ )
+)
+The parameters for the assets.
+classmethod
+
+
+check_position_is_region(
+ params: TextAssetParams,
+) -> TextAssetParams
+Validate that the subtitle positioning is of type RegionPosition.
+ +src/mosaico/assets/subtitle.pyclassmethod
+
+
+from_shot(shot: Shot, **kwargs: Any) -> SubtitleAsset
+Create a SubtitleAsset from a Shot.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
shot |
+
+ Shot
+ |
+
+
+
+ The shot to create the asset from. + |
+ + required + | +
kwargs |
+
+ Any
+ |
+
+
+
+ Additional parameters for the asset. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ SubtitleAsset
+ |
+
+
+
+ The created asset. + |
+
src/mosaico/assets/subtitle.py
+ Bases: BaseModel
Represents the parameters for a text assets.
+ + + + +class-attribute
+ instance-attribute
+
+
+position: Position = Field(default_factory=AbsolutePosition)
+The positioning of the text assets in the video.
+class-attribute
+ instance-attribute
+
+
+font_family: str = 'Arial Bold'
+The font family.
+class-attribute
+ instance-attribute
+
+
+font_size: NonNegativeInt = 70
+The font size.
+class-attribute
+ instance-attribute
+
+
+The font color hexadecimal code.
+class-attribute
+ instance-attribute
+
+
+font_kerning: float = 0
+The font kerning.
+class-attribute
+ instance-attribute
+
+
+line_height: int = 10
+The line height.
+class-attribute
+ instance-attribute
+
+
+The font stroke color hexadecimal code.
+class-attribute
+ instance-attribute
+
+
+stroke_width: NonNegativeFloat = 0
+The font stroke width.
+class-attribute
+ instance-attribute
+
+
+The shadow color hexadecimal code.
+class-attribute
+ instance-attribute
+
+
+shadow_blur: int = 0
+The shadow blur.
+class-attribute
+ instance-attribute
+
+
+The shadow opacity.
+class-attribute
+ instance-attribute
+
+
+shadow_angle: int = 0
+The shadow angle.
+class-attribute
+ instance-attribute
+
+
+shadow_distance: NonNegativeInt = 0
+The shadow distance.
+class-attribute
+ instance-attribute
+
+
+The background color hexadecimal code.
+class-attribute
+ instance-attribute
+
+
+align: Literal['left', 'center', 'right'] = 'left'
+The text alignment.
+class-attribute
+ instance-attribute
+
+
+z_index: int = 0
+The z-index of the assets.
+Serialize the color to its hexadecimal code.
+ + +
+ Bases: BaseAsset[TextAssetParams]
Represents a text assets with various properties.
+ + + + +class-attribute
+ instance-attribute
+
+
+params: TextAssetParams = Field(
+ default_factory=TextAssetParams
+)
+The parameters for the text assets.
+property
+
+
+has_background: bool
+Check if the text asset has a background.
+property
+
+
+has_shadow: bool
+Check if the text asset has a shadow.
+
+ Bases: BaseTextAsset
Represents a text assets with various properties.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['text'] = 'text'
+¨The type of the assets. Defaults to "text".
+
+ Bases: BaseModel
Transcriber using AssemblyAI's API.
+ + + + +class-attribute
+ instance-attribute
+
+
+api_key: str | None = None
+API key for AssemblyAI.
+class-attribute
+ instance-attribute
+
+
+model: Literal['best', 'nano'] = 'best'
+Model to use for transcription.
+class-attribute
+ instance-attribute
+
+
+language: LanguageAlpha2 | None = None
+Language of the transcription.
+class-attribute
+ instance-attribute
+
+
+Custom spelling dictionary for the transcription.
+transcribe(audio_asset: AudioAsset) -> Transcription
+Transcribe audio using AssemblyAI's API.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
audio_asset |
+
+ AudioAsset
+ |
+
+
+
+
+ |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Transcription
+ |
+
+
+
+ The transcription. + |
+
src/mosaico/audio_transcribers/assemblyai.py
+ Bases: Protocol
A protocol defining the interface for audio transcription services.
+This protocol specifies the contract that all audio transcribers in the Mosaico
+project should adhere to. It defines a single method, :meth:transcribe, which
+takes an audio asset and returns a transcription.
Implementations of this protocol can use various transcription technologies, +such as speech-to-text APIs, local models, or custom algorithms. The protocol +ensures a consistent interface regardless of the underlying implementation.
+Note
+This is a runtime checkable protocol, which means isinstance() and
+issubclass() checks can be performed against it.
Example:
+ class MyTranscriber:
+ def transcribe(self, audio_asset: AudioAsset) -> Transcription:
+ # Implement transcription logic here
+ ...
+
+ transcriber: AudioTranscriber = MyTranscriber()
+ transcription = transcriber.transcribe(my_audio_asset)
+transcribe(audio_asset: AudioAsset) -> Transcription
+Transcribe speech from an audio asset to text.
+This method should implement the core logic for converting speech in the +provided audio asset into text. The specific implementation can vary +based on the transcription technology being used.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
audio_asset |
+
+ AudioAsset
+ |
+
+
+
+ The audio asset containing the speech to be transcribed. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Transcription
+ |
+
+
+
+ A Transcription object containing the text transcription of the speech. .. note:: The implementation should handle various audio formats and durations as defined by the :class: |
+
src/mosaico/audio_transcribers/protocol.py
+ Bases: BaseModel
Transcriber using OpenAI's Whisper API.
+ + + + +class-attribute
+ instance-attribute
+
+
+api_key: str | None = None
+API key for OpenAI's Whisper API.
+class-attribute
+ instance-attribute
+
+
+base_url: str | None = None
+Base URL for OpenAI's Whisper API.
+class-attribute
+ instance-attribute
+
+
+timeout: PositiveInt = 120
+Timeout for transcription in seconds.
+class-attribute
+ instance-attribute
+
+
+model: Literal['whisper-1'] = 'whisper-1'
+Model to use for transcription.
+class-attribute
+ instance-attribute
+
+
+The sampling temperature for the model.
+class-attribute
+ instance-attribute
+
+
+language: LanguageAlpha2 | None = None
+Language of the transcription.
+transcribe(audio_asset: AudioAsset) -> Transcription
+Transcribe audio using OpenAI's Whisper API.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
audio_asset |
+
+ AudioAsset
+ |
+
+
+
+ The audio asset to transcribe. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Transcription
+ |
+
+
+
+ The transcription words. + |
+
src/mosaico/audio_transcribers/openai.py
+ Bases: BaseClipMaker[AudioAsset]
A clip maker for audio assets.
+The audio clip maker performs these transformations:
+Examples:
+# Create a basic audio clip
+maker = AudioClipMaker(duration=5.0)
+clip = maker.make_clip(audio_asset)
+
+# Create clip with custom duration
+clip = maker.make_clip(audio_asset, duration=10.0)
+
+ Bases: BaseClipMaker[ImageAsset]
A clip maker for image assets.
+The image clip maker performs these transformations:
+Examples:
+# Create a basic image clip
+maker = ImageClipMaker(duration=5.0, video_resolution=(1920, 1080))
+clip = maker.make_clip(image_asset)
+
+# Create clip with background resize
+image_asset.params.as_background = True
+clip = maker.make_clip(image_asset) # Will resize to match resolution
+
+# Create clip with custom position
+image_asset.params.position = AbsolutePosition(x=100, y=50)
+clip = maker.make_clip(image_asset) # Will position at x=100, y=50
+
+ Bases: Protocol[T_contra]
A protocol for clip makers.
+ + + + +
+ Bases: BaseModel, Generic[T], ABC
Base class for clip makers.
+ + + + +class-attribute
+ instance-attribute
+
+
+duration: NonNegativeFloat | None = None
+The duration of the clip in seconds.
+class-attribute
+ instance-attribute
+
+
+The resolution of the video.
+class-attribute
+ instance-attribute
+
+
+List of effects to apply to the clip.
+make_clip(asset: T) -> Clip
+Make a clip from the given clip, duration and video resolution.
+:clip: The clip to make the clip from. +:duration: The duration of the clip in seconds. +:video_resolution: The resolution of the video.
+ + +Returns:
+| Type | +Description | +
|---|---|
+ Clip
+ |
+
+
+
+ The clip. + |
+
src/mosaico/clip_makers/base.pyGet a clip maker class.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_type |
+
+ AssetType
+ |
+
+
+
+ The assets type. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ type[ClipMaker]
+ |
+
+
+
+ The clip maker class. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If no clip maker is found for the given assets type and name. + |
+
src/mosaico/clip_makers/factory.pymake_clip(
+ asset: Asset,
+ duration: float | None = None,
+ video_resolution: FrameSize | None = None,
+ effects: Sequence[Effect] | None = None,
+ **kwargs: Any
+) -> Clip
+Make a clip from the given asset.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset |
+
+ Asset
+ |
+
+
+
+ The asset. + |
+ + required + | +
duration |
+
+ float | None
+ |
+
+
+
+ The duration of the clip. + |
+
+ None
+ |
+
video_resolution |
+
+ FrameSize | None
+ |
+
+
+
+ The resolution of the video. + |
+
+ None
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Clip
+ |
+
+
+
+ The clip. + |
+
src/mosaico/clip_makers/factory.py
+ Bases: TextClipMaker
A clip maker for subtitle assets.
+The subtitle clip maker performs these transformations:
+Note
+For further details, refer to the TextClipMaker documentation.
+Examples:
+# Create a basic subtitle clip
+maker = SubtitleClipMaker(duration=5.0, video_resolution=(1920, 1080))
+clip = maker.make_clip(subtitle_asset)
+
+ Bases: BaseClipMaker[BaseTextAsset]
A clip maker for text assets.
+The process of text clip creation involves:
+Font and Text Preparation:
+Shadow Creation (if enabled):
+Text Rendering:
+Image Composition:
+Clip Creation:
+Examples:
+# Create a basic text clip
+maker = TextClipMaker(duration=5.0, video_resolution=(1920, 1080))
+clip = maker.make_clip(text_asset)
+
+# Create clip with shadow
+text_asset.params.has_shadow = True
+clip = maker.make_clip(text_asset) # Will add shadow effect
+
+# Create clip with custom position
+text_asset.params.position = AbsolutePosition(x=100, y=50)
+clip = maker.make_clip(text_asset) # Will position at x=100, y=50
+
+# Create clip with custom font size
+text_asset.params.font_size = 48
+clip = maker.make_clip(text_asset) # Will render text with font size 48
+
+ Bases: Protocol[ClipType]
A protocol for clip effects.
+Note
+This is a runtime checkable protocol, which means isinstance() and
+issubclass() checks can be performed against it.
module-attribute
+
+
+VideoEffect = (
+ ZoomInEffect
+ | ZoomOutEffect
+ | PanLeftEffect
+ | PanRightEffect
+ | PanUpEffect
+ | PanDownEffect
+)
+A type representing any video effect.
+module-attribute
+
+
+VideoEffectType = Literal[
+ "zoom_in",
+ "zoom_out",
+ "pan_left",
+ "pan_right",
+ "pan_up",
+ "pan_down",
+]
+A type representing the type of a video effect.
+module-attribute
+
+
+The pan function type.
+
+ Bases: BaseModel
A pan effect.
+ + + + +class-attribute
+ instance-attribute
+
+
+zoom_factor: PositiveFloat = 1.1
+The zoom factor.
+Apply the pan effect to the clip.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
clip |
+
+ VideoClip
+ |
+
+
+
+ The clip. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoClip
+ |
+
+
+
+ The clip with the effect applied. + |
+
src/mosaico/effects/pan.py
+ Bases: BasePanEffect
A left to right pan effect.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['pan_right'] = 'pan_right'
+Effect type. Must be "pan_right".
+
+ Bases: BasePanEffect
A right to left pan effect.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['pan_left'] = 'pan_left'
+Effect type. Must be "pan_left".
+
+ Bases: BasePanEffect
A top to bottom pan effect.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['pan_down'] = 'pan_down'
+Effect type. Must be "pan_down".
+
+ Bases: BasePanEffect
A bottom to top pan effect.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['pan_up'] = 'pan_up'
+Effect type. Must be "pan_up".
+
+ Bases: BaseModel
Base class for zoom effects.
+ + + + +instance-attribute
+
+
+Starting zoom scale (1.0 is original size).
+instance-attribute
+
+
+Ending zoom scale.
+Apply zoom effect to clip.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
clip |
+
+ VideoClip
+ |
+
+
+
+ The clip to apply the effect to. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoClip
+ |
+
+
+
+ The clip with the effect applied. + |
+
src/mosaico/effects/zoom.py
+ Bases: BaseZoomEffect
Zoom-in effect for video clips.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['zoom_in'] = 'zoom_in'
+Effect type. Must be "zoom_in".
+class-attribute
+ instance-attribute
+
+
+Starting zoom scale (1.0 is original size).
+
+ Bases: BaseZoomEffect
Zoom-out effect for video clips.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['zoom_out'] = 'zoom_out'
+Effect type. Must be "zoom_out".
+class-attribute
+ instance-attribute
+
+
+Starting zoom scale (1.5 times the original size).
+
+ Bases: BaseModel
Represents a media object.
+ + + + +class-attribute
+ instance-attribute
+
+
+The unique identifier of the assets.
+class-attribute
+ instance-attribute
+
+
+The content of the media.
+class-attribute
+ instance-attribute
+
+
+The path to the media.
+class-attribute
+ instance-attribute
+
+
+mime_type: str | None = None
+The MIME type of the media.
+class-attribute
+ instance-attribute
+
+
+encoding: str = 'utf-8'
+The encoding of the media.
+class-attribute
+ instance-attribute
+
+
+The metadata of the media.
+property
+
+
+description: str
+Returns a description of the media.
+property
+
+
+credit: str
+Returns the credits of the media.
+classmethod
+
+
+Validates the content of the media.
+ +src/mosaico/media.pyclassmethod
+
+
+from_path(
+ path: PathLike,
+ *,
+ encoding: str = "utf-8",
+ mime_type: str | None = None,
+ guess_mime_type: bool = True,
+ metadata: dict | None = None,
+ **kwargs: Any
+) -> Self
+Creates a media from a path.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
path |
+
+ PathLike
+ |
+
+
+
+ The path to the media. + |
+ + required + | +
encoding |
+
+ str
+ |
+
+
+
+ The encoding of the media. + |
+
+ 'utf-8'
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the media. + |
+
+ None
+ |
+
guess_mime_type |
+
+ bool
+ |
+
+
+
+ Whether to guess the MIME type. + |
+
+ True
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the media. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The media. + |
+
src/mosaico/media.pyclassmethod
+
+
+from_data(
+ data: str | bytes,
+ *,
+ path: PathLike | None = None,
+ metadata: dict | None = None,
+ mime_type: str | None = None,
+ **kwargs: Any
+) -> Self
+Creates a media from data.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ str | bytes
+ |
+
+
+
+ The data of the media. + |
+ + required + | +
path |
+
+ PathLike | None
+ |
+
+
+
+ The path to the media. + |
+
+ None
+ |
+
metadata |
+
+ dict | None
+ |
+
+
+
+ The metadata of the media. + |
+
+ None
+ |
+
mime_type |
+
+ str | None
+ |
+
+
+
+ The MIME type of the media. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to the constructor. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Self
+ |
+
+
+
+ The media. + |
+
src/mosaico/media.pyclassmethod
+
+
+Converts an external representation to a media.
+ +src/mosaico/media.pyConverts the media to an external representation.
+ +src/mosaico/media.pyto_string() -> str
+Returns the media as a string.
+ +src/mosaico/media.pyto_bytes() -> bytes
+Returns the media as bytes.
+ +src/mosaico/media.pyto_bytes_io() -> Generator[BytesIO | BufferedReader]
+Read data as a byte stream.
+ +src/mosaico/media.py
+ Bases: BaseModel
Represents an absolute positioning.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['absolute'] = 'absolute'
+The type of positioning. Defaults to "absolute".
+class-attribute
+ instance-attribute
+
+
+x: NonNegativeInt = 0
+The x-coordinate of the assets.
+class-attribute
+ instance-attribute
+
+
+y: NonNegativeInt = 0
+The y-coordinate of the assets.
+classmethod
+
+
+from_relative(
+ position: RelativePosition, frame_size: FrameSize
+) -> AbsolutePosition
+Creates an absolute positioning from a relative positioning.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ RelativePosition
+ |
+
+
+
+ The relative positioning. + |
+ + required + | +
frame_size |
+
+ FrameSize
+ |
+
+
+
+ The size of the frame. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AbsolutePosition
+ |
+
+
+
+ The absolute positioning. + |
+
src/mosaico/positioning/absolute.pyclassmethod
+
+
+from_region(
+ position: RegionPosition, frame_size: FrameSize
+) -> AbsolutePosition
+Creates an absolute positioning from a region positioning.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ RegionPosition
+ |
+
+
+
+ The region positioning. + |
+ + required + | +
frame_max_width |
+ + | +
+
+
+ The maximum width of the frame. + |
+ + required + | +
frame_max_height |
+ + | +
+
+
+ The maximum height of the frame. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AbsolutePosition
+ |
+
+
+
+ The absolute positioning. + |
+
src/mosaico/positioning/absolute.pymodule-attribute
+
+
+PositionType = Literal['absolute', 'relative', 'region']
+An enumeration of the different types of positions that can be held in an assets.
+module-attribute
+
+
+Position = Union[
+ AbsolutePosition, RelativePosition, RegionPosition
+]
+Represents a positioning of an assets in the frame.
+convert_position_to_absolute(
+ position: Position, frame_size: FrameSize
+) -> AbsolutePosition
+Convert a relative position to an absolute position.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ Position
+ |
+
+
+
+ The position to be converted. + |
+ + required + | +
frame_size |
+
+ FrameSize
+ |
+
+
+
+ The size of the frame. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ AbsolutePosition
+ |
+
+
+
+ The converted absolute positioning object. + |
+
src/mosaico/positioning/utils.pyCheck if the position is a region position.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ Position
+ |
+
+
+
+ The position to be checked. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ Whether the position is a region position. + |
+
src/mosaico/positioning/utils.pyCheck if the position is a relative position.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ Position
+ |
+
+
+
+ The position to be checked. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ Whether the position is a relative position. + |
+
src/mosaico/positioning/utils.pyCheck if the position is an absolute position.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
position |
+
+ Position
+ |
+
+
+
+ The position to be checked. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ bool
+ |
+
+
+
+ Whether the position is an absolute position. + |
+
src/mosaico/positioning/utils.pymodule-attribute
+
+
+RegionX = Literal['left', 'center', 'right']
+The possible region x-coordinates of the assets.
+module-attribute
+
+
+RegionY = Literal['top', 'center', 'bottom']
+The possible region y-coordinates of the assets.
+
+ Bases: BaseModel
Represents a region positioning.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['region'] = 'region'
+The type of positioning. Defaults to "region".
+class-attribute
+ instance-attribute
+
+
+x: RegionX = 'center'
+The region x-coordinate of the assets.
+class-attribute
+ instance-attribute
+
+
+y: RegionY = 'center'
+The region y-coordinate of the assets.
+classmethod
+
+
+from_string(string: str) -> RegionPosition
+Create a region position from a string.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
string |
+
+ str
+ |
+
+
+
+ The string to parse. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ RegionPosition
+ |
+
+
+
+ The region position. + |
+
src/mosaico/positioning/region.py
+ Bases: BaseModel
Represents a relative position.
+ + + + +class-attribute
+ instance-attribute
+
+
+type: Literal['relative'] = 'relative'
+The type of position. Defaults to "relative".
+class-attribute
+ instance-attribute
+
+
+x: NonNegativeFloat = 0.5
+The x-coordinate of the assets.
+class-attribute
+ instance-attribute
+
+
+y: NonNegativeFloat = 0.5
+The y-coordinate of the assets.
+
+ Bases: BaseModel
Represents a unit of grouped asset references in a timeline.
+ + + + +class-attribute
+ instance-attribute
+
+
+title: str | None = None
+An optional title of the scene.
+class-attribute
+ instance-attribute
+
+
+description: str | None = None
+An optional description of the scene.
+class-attribute
+ instance-attribute
+
+
+asset_references: list[AssetReference] = Field(
+ default_factory=list
+)
+A list of assets associated with the scene.
+property
+
+
+start_time: float
+The start time of the scene in seconds.
+property
+
+
+end_time: float
+The end time of the scene in seconds.
+property
+
+
+duration: float
+The duration of the scene in seconds.
+property
+
+
+has_audio: bool
+Check if the scene has an audio asset.
+property
+
+
+has_subtitles: bool
+Check if the scene has a subtitle asset.
+classmethod
+
+
+Create a scene from a dictionary.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ Mapping[str, Any]
+ |
+
+
+
+ The dictionary data. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Scene
+ |
+
+
+
+ The scene. + |
+
src/mosaico/scene.pyadd_asset_references(
+ references: AssetReference | Sequence[AssetReference],
+) -> Scene
+Add asset references to the scene.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
references |
+
+ AssetReference | Sequence[AssetReference]
+ |
+
+
+
+ The asset references to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Scene
+ |
+
+
+
+ The scene. + |
+
src/mosaico/scene.pyRemove asset references by asset ID.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_id |
+
+ str
+ |
+
+
+
+ The asset ID to remove. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Scene
+ |
+
+
+
+ The scene. + |
+
src/mosaico/scene.pywith_subtitle_params(
+ params: TextAssetParams | Mapping[str, Any]
+) -> Scene
+Add subtitle asset params to the scene.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
params |
+
+ TextAssetParams | Mapping[str, Any]
+ |
+
+
+
+ The subtitle asset params. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Scene
+ |
+
+
+
+ The scene. + |
+
src/mosaico/scene.py
+ Bases: Protocol
A protocol for generating a shooting script from a list of media files.
+This protocol defines the interface for generating a shooting script for a project from a list of media objects.
+The generate method should be implemented by concrete classes and should fullfill the contract of this protocol
+by returning a shooting script containing the shots generated from the media files.
Concrete implementations of the ScriptGenerator protocol can be used by the VideoProjectBuilder class to
+automatically generate a shooting script for a project, avoiding the need of a manually defined timeline.
Note
+This is a runtime checkable protocol, which means isinstance() and
+issubclass() checks can be performed against it.
Example:
+class MyScriptGenerator:
+ def generate(self, media: Sequence[Media], **kwargs: Any) -> ShootingScript:
+ # Implement script generation logic here
+ ...
+
+generator: ScriptGenerator = MyScriptGenerator()
+script = generator.generate(my_media_files)
+generate(
+ media: Sequence[Media], **kwargs: Any
+) -> ShootingScript
+Generate a shooting script from a list of media files.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
media |
+
+ Sequence[Media]
+ |
+
+
+
+ The list of media objects. + |
+ + required + | +
kwargs |
+
+ Any
+ |
+
+
+
+ Additional context for the script generation. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ ShootingScript
+ |
+
+
+
+ The shooting script generated from the media files. + |
+
src/mosaico/script_generators/protocol.py
+ Bases: BaseModel
A shot for a script.
+ + + + +instance-attribute
+
+
+number: PositiveInt
+The number of the shot.
+instance-attribute
+
+
+description: str
+The description of the shot.
+instance-attribute
+
+
+start_time: NonNegativeFloat
+The start time of the shot in seconds.
+instance-attribute
+
+
+end_time: PositiveFloat
+The end time of the shot in seconds.
+instance-attribute
+
+
+subtitle: str
+The subtitle for the shot.
+instance-attribute
+
+
+media_id: str
+The media reference for the shot.
+class-attribute
+ instance-attribute
+
+
+effects: list[VideoEffectType] = Field(default_factory=list)
+The effects applied to the shot.
+property
+
+
+duration: float
+The duration of the shot in seconds.
+
+ Bases: BaseModel
A shooting script for a video project.
+ + + + +instance-attribute
+
+
+title: str
+The title of the script.
+class-attribute
+ instance-attribute
+
+
+description: str | None = None
+The description of the script.
+class-attribute
+ instance-attribute
+
+
+The shots in the script.
+property
+
+
+duration: float
+The total duration of the script in seconds.
+property
+
+
+shot_count: int
+The number of shots in the script.
+
+ Bases: BaseModel
Speech synthesizer for ElevenLabs.
+ + + + +class-attribute
+
+
+provider: str = 'elevenlabs'
+Provider name for ElevenLabs.
+class-attribute
+ instance-attribute
+
+
+api_key: str | None = None
+API key for ElevenLabs.
+instance-attribute
+
+
+voice_id: str
+Voice ID for ElevenLabs.
+class-attribute
+ instance-attribute
+
+
+Voice stability for the synthesized speech. It ranges from 0 to 1. Default is 0.5.
+class-attribute
+ instance-attribute
+
+
+Voice similarity boost for the synthesized speech. It ranges from 0 to 1. Default is 0.5.
+class-attribute
+ instance-attribute
+
+
+Voice style for the synthesized speech. It ranges from 0 to 1. Default is 0.5.
+class-attribute
+ instance-attribute
+
+
+voice_speaker_boost: bool = True
+Voice speaker boost for the synthesized speech. Default is True.
+class-attribute
+ instance-attribute
+
+
+language_code: LanguageAlpha2 = Field(
+ default_factory=lambda: LanguageAlpha2("en")
+)
+Language code of the text to synthesize. If not provided, it defaults to "en".
+Check the ElevenLabs API documentation for the list of supported languages by model. +https://help.elevenlabs.io/hc/en-us/articles/17883183930129-What-models-do-you-offer-and-what-is-the-difference-between-them
+class-attribute
+ instance-attribute
+
+
+model: Literal[
+ "eleven_turbo_v2_5",
+ "eleven_turbo_v2",
+ "eleven_multilingual_v2",
+ "eleven_monolingual_v1",
+ "eleven_multilingual_v1",
+] = "eleven_multilingual_v2"
+Model ID for ElevenLabs.
+class-attribute
+ instance-attribute
+
+
+timeout: int = 120
+Timeout for the HTTP request in seconds.
+synthesize(
+ texts: Sequence[str],
+ *,
+ audio_params: AudioAssetParams | None = None,
+ **kwargs: Any
+) -> list[AudioAsset]
+Synthesizes the given texts into audio assets using the ElevenLabs API.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
texts |
+
+ Sequence[str]
+ |
+
+
+
+ List of texts to synthesize. + |
+ + required + | +
audio_params |
+
+ AudioAssetParams | None
+ |
+
+
+
+ Audio parameters for the synthesized audio assets. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[AudioAsset]
+ |
+
+
+
+ List of synthesized audio assets. + |
+
src/mosaico/speech_synthesizers/elevenlabs.py
+ Bases: Protocol
Protocol defining the interface for text-to-speech synthesis services.
+The SpeechSynthesizer protocol standardizes how text is converted to speech across +different TTS providers (e.g., Google Cloud TTS, Azure Speech). Implementations +of this protocol handle the specifics of communicating with TTS services and managing +the generated audio assets.
+Implementations should handle:
+Example:
+class MySpeechSynthesizer(SpeechSynthesizer):
+ provider = "my-provider"
+
+ def synthesize(self, texts, audio_params=None):
+ # Implementation details
+ pass
+
+synthesizer = MySpeechSynthesizer()
+audio_assets = synthesizer.synthesize(
+ texts=["Hello world", "Welcome to the demo"],
+ audio_params=AudioAssetParams(volume=0.8)
+)
+Attributes:
+| Name | +Type | +Description | +
|---|---|---|
provider |
+
+ str
+ |
+
+
+
+ Identifier for the TTS service provider (e.g., "openai", "assemblyai", "azure"). This should be a unique string that identifies the implementation. + |
+
class-attribute
+
+
+provider: str
+The provider of the speech synthesizer.
+synthesize(
+ texts: Sequence[str],
+ *,
+ audio_params: AudioAssetParams | None = None,
+ **kwargs: Any
+) -> list[AudioAsset]
+Convert a list of texts into synthesized speech audio assets.
+This method handles the conversion of text to speech, managing both the synthesis +process and the creation of audio assets for use in video projects.
+Note
+Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
texts |
+
+ Sequence[str]
+ |
+
+
+
+ List of text strings to be converted to speech. Each string should be properly formatted text ready for synthesis. + |
+ + required + | +
audio_params |
+
+ AudioAssetParams | None
+ |
+
+
+
+ Optional parameters for configuring the output audio assets. If None, default parameters will be used. These parameters affect properties like sample rate, channels, etc. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional provider-specific parameters. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[AudioAsset]
+ |
+
+
+
+ List of audio assets containing the synthesized speech. The returned list will have the same length as the input texts list, with corresponding indices. + |
+
src/mosaico/speech_synthesizers/protocol.py
+ Bases: BaseModel
Speech synthesizer using OpenAI's API.
+ + + + +class-attribute
+
+
+provider: str = 'openai'
+Provider name for OpenAI.
+class-attribute
+ instance-attribute
+
+
+api_key: str | None = None
+API key for OpenAI's API.
+class-attribute
+ instance-attribute
+
+
+base_url: str | None = None
+Base URL for OpenAI's API.
+class-attribute
+ instance-attribute
+
+
+model: Literal['tts-1', 'tts-1-hd'] = 'tts-1'
+Model to use for speech synthesis.
+class-attribute
+ instance-attribute
+
+
+voice: Literal[
+ "alloy", "echo", "fable", "onyx", "nova", "shimmer"
+] = "alloy"
+Voice to use for speech synthesis.
+class-attribute
+ instance-attribute
+
+
+Speed of speech synthesis.
+class-attribute
+ instance-attribute
+
+
+timeout: PositiveInt = 120
+Timeout for speech synthesis in seconds.
+synthesize(
+ texts: Sequence[str],
+ *,
+ audio_params: AudioAssetParams | None = None,
+ **kwargs: Any
+) -> list[AudioAsset]
+Synthesize speech from texts using OpenAI's API.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
texts |
+
+ Sequence[str]
+ |
+
+
+
+ Texts to synthesize. + |
+ + required + | +
audio_params |
+
+ AudioAssetParams | None
+ |
+
+
+
+ Parameters for the audio asset. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional parameters for the OpenAI API. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ list[AudioAsset]
+ |
+
+
+
+ List of audio assets. + |
+
src/mosaico/speech_synthesizers/openai.pymodule-attribute
+
+
+TimelineEvent = AssetReference | Scene
+A type alias for a timeline event, which can be an asset reference or a scene.
+
+ Bases: BaseModel
A dictionary representing the configuration of a project.
+ + + + +class-attribute
+ instance-attribute
+
+
+title: str = 'Untitled Project'
+The title of the project. Defaults to "Untitled Project".
+class-attribute
+ instance-attribute
+
+
+version: int = 1
+The version of the project. Defaults to 1.
+class-attribute
+ instance-attribute
+
+
+The resolution of the project in pixels. Defaults to 1920x1080.
+class-attribute
+ instance-attribute
+
+
+fps: PositiveInt = 30
+The frames per second of the project. Defaults to 30.
+
+ Bases: BaseModel
Represents a project with various properties and methods to manipulate its data.
+ + + + +class-attribute
+ instance-attribute
+
+
+config: VideoProjectConfig = Field(
+ default_factory=VideoProjectConfig
+)
+The configuration of the project.
+class-attribute
+ instance-attribute
+
+
+A dictionary mapping assets keys to Asset objects.
+class-attribute
+ instance-attribute
+
+
+timeline: Timeline = Field(default_factory=Timeline)
+The timeline of assets and scenes of the video.
+property
+
+
+duration: float
+The total duration of the project in seconds.
+classmethod
+
+
+from_dict(data: dict[str, Any]) -> VideoProject
+Create a Project object from a dictionary.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
data |
+
+ dict[str, Any]
+ |
+
+
+
+ The dictionary containing the project data. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ A Project object instance. + |
+
src/mosaico/video/project.pyclassmethod
+
+
+from_file(path: PathLike) -> VideoProject
+Create a Project object from a YAML file.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
path |
+
+ PathLike
+ |
+
+
+
+ The path to the YAML file. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ A Project object instance. + |
+
src/mosaico/video/project.pyclassmethod
+
+
+from_script_generator(
+ script_generator: ScriptGenerator,
+ media: Sequence[Media],
+ *,
+ config: VideoProjectConfig | None = None,
+ **kwargs: Any
+) -> VideoProject
+Create a Project object from a script generator.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
generator |
+ + | +
+
+
+ The script generator to use. + |
+ + required + | +
media |
+
+ Sequence[Media]
+ |
+
+
+
+ The media files to use. + |
+ + required + | +
config |
+
+ VideoProjectConfig | None
+ |
+
+
+
+ The configuration of the project. + |
+
+ None
+ |
+
kwargs |
+
+ Any
+ |
+
+
+
+ Additional keyword arguments to pass to the script generator. + |
+
+ {}
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ A Project object instance. + |
+
src/mosaico/video/project.pyWrite the Project object to a YAML file.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
path |
+
+ PathLike
+ |
+
+
+
+ The path to the YAML file. + |
+ + required + | +
src/mosaico/video/project.pyadd_assets(assets: AssetInputType) -> VideoProject
+Add one or more assets to the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
assets |
+
+ AssetInputType
+ |
+
+
+
+ The asset or list of assets to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pyadd_timeline_events(
+ events: EventOrEventSequence,
+) -> VideoProject
+Add one or more events to the timeline.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
events |
+
+ EventOrEventSequence
+ |
+
+
+
+ The event or list of events to add. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If an asset referenced in the events does not exist in the project. + |
+
src/mosaico/video/project.pyadd_narration(
+ speech_synthesizer: SpeechSynthesizer,
+) -> VideoProject
+Add narration to subtitles inside Scene objects by generating speech audio from subtitle text.
+Updates other asset timings within each Scene based on generated speech duration.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
speech_synthesizer |
+
+ SpeechSynthesizer
+ |
+
+
+
+ The speech synthesizer to use for generating narration audio + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project with narration added + |
+
src/mosaico/video/project.pyadd_captions(
+ transcription: Transcription,
+ *,
+ max_duration: int = 5,
+ params: TextAssetParams | None = None,
+ scene_index: int | None = None,
+ overwrite: bool = False
+) -> VideoProject
+Add subtitles to the project from a transcription.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
transcription |
+
+ Transcription
+ |
+
+
+
+ The transcription to add subtitles from. + |
+ + required + | +
max_duration |
+
+ int
+ |
+
+
+
+ The maximum duration of each subtitle. + |
+
+ 5
+ |
+
params |
+
+ TextAssetParams | None
+ |
+
+
+
+ The parameters for the subtitle assets. + |
+
+ None
+ |
+
scene_index |
+
+ int | None
+ |
+
+
+
+ The index of the scene to add the subtitles to. + |
+
+ None
+ |
+
overwrite |
+
+ bool
+ |
+
+
+
+ Whether to overwrite existing subtitles in the scene. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.py297 +298 +299 +300 +301 +302 +303 +304 +305 +306 +307 +308 +309 +310 +311 +312 +313 +314 +315 +316 +317 +318 +319 +320 +321 +322 +323 +324 +325 +326 +327 +328 +329 +330 +331 +332 +333 +334 +335 +336 +337 +338 +339 +340 +341 +342 +343 +344 +345 +346 +347 +348 +349 +350 +351 +352 +353 +354 +355 +356 +357 +358 +359 +360 +361 +362 +363 +364 +365 +366 +367 +368 +369 +370 +371 +372 +373 +374 +375 +376 +377 +378 +379 +380 +381 +382 +383 +384 +385 | |
add_captions_from_transcriber(
+ audio_transcriber: AudioTranscriber,
+ *,
+ max_duration: int = 5,
+ params: TextAssetParams | None = None,
+ overwrite: bool = False
+) -> VideoProject
+Add subtitles to the project from audio assets using an audio transcriber.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
audio_transcriber |
+
+ AudioTranscriber
+ |
+
+
+
+ The audio transcriber to use for transcribing audio assets. + |
+ + required + | +
max_duration |
+
+ int
+ |
+
+
+
+ The maximum duration of each subtitle. + |
+
+ 5
+ |
+
params |
+
+ TextAssetParams | None
+ |
+
+
+
+ The parameters for the subtitle assets. + |
+
+ None
+ |
+
overwrite |
+
+ bool
+ |
+
+
+
+ Whether to overwrite existing subtitles in the scene. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pywith_subtitle_params(
+ params: TextAssetParams | Mapping[str, Any]
+) -> VideoProject
+Override the subtitle parameters for the assets in the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
params |
+
+ TextAssetParams | Mapping[str, Any]
+ |
+
+
+
+ The subtitle parameters to set. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pywith_title(title: str) -> VideoProject
+Override the title of the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
title |
+
+ str
+ |
+
+
+
+ The title to set. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pywith_version(version: int) -> VideoProject
+Override the project version.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
version |
+
+ int
+ |
+
+
+
+ The version to set. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pywith_fps(fps: int) -> VideoProject
+Override the FPS of the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
fps |
+
+ int
+ |
+
+
+
+ The FPS to set. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
with_resolution(resolution: FrameSize) -> VideoProject
+Override the resolution of the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
resolution |
+
+ FrameSize
+ |
+
+
+
+ The resolution to set. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pyGet an asset by its ID.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_id |
+
+ str
+ |
+
+
+
+ The ID of the asset. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ Asset
+ |
+
+
+
+ The Asset object. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If the asset is not found in the project assets. + |
+
src/mosaico/video/project.pyget_timeline_event(index: int) -> TimelineEvent
+Get a timeline event by its index.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ The index of the timeline event. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ TimelineEvent
+ |
+
+
+
+ The TimelineEvent object. + |
+
Raises:
+| Type | +Description | +
|---|---|
+ ValueError
+ |
+
+
+
+ If the index is out of range. + |
+
src/mosaico/video/project.pyremove_asset(asset_id: str) -> VideoProject
+Remove an asset from the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
asset_id |
+
+ str
+ |
+
+
+
+ The ID of the asset to remove. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pyremove_timeline_event(index: int) -> VideoProject
+Remove a timeline event from the project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
index |
+
+ int
+ |
+
+
+
+ The index of the timeline event to remove. + |
+ + required + | +
Returns:
+| Type | +Description | +
|---|---|
+ VideoProject
+ |
+
+
+
+ The updated project. + |
+
src/mosaico/video/project.pyrender_video(
+ project: VideoProject,
+ output_dir: str | Path,
+ *,
+ overwrite: bool = False
+) -> Path
+Renders a video based on a project.
+ + +Parameters:
+| Name | +Type | +Description | +Default | +
|---|---|---|---|
project |
+
+ VideoProject
+ |
+
+
+
+ The project to render. + |
+ + required + | +
output_dir |
+
+ str | Path
+ |
+
+
+
+ The output directory. + |
+ + required + | +
overwrite |
+
+ bool
+ |
+
+
+
+ Whether to overwrite the output file if it already exists. + |
+
+ False
+ |
+
Returns:
+| Type | +Description | +
|---|---|
+ Path
+ |
+
+
+
+ The path to the rendered video. + |
+
src/mosaico/video/rendering.py