pycaps-ai 0.2.1__py3-none-any.whl

pycaps/__init__.py

@@ -0,0 +1,13 @@
+from .pipeline import CapsPipeline, CapsPipelineBuilder, JsonConfigLoader
+from .renderer import CssSubtitleRenderer, PictexSubtitleRenderer
+from .transcriber import WhisperAudioTranscriber, GoogleAudioTranscriber, AudioTranscriber, LimitByWordsSplitter, LimitByCharsSplitter, SplitIntoSentencesSplitter, TranscriptFormat, load_transcription
+from .effect import *
+from .animation import *
+from .selector import WordClipSelector
+from .tag import TagCondition, BuiltinTag, TagConditionFactory, SemanticTagger
+from .common import *
+from .layout.definitions import *
+from .ai import LlmProvider
+from .template import TemplateLoader, TemplateFactory, DEFAULT_TEMPLATE_NAME
+
+__version__ = "0.2.1" 

pycaps/ai/__init__.py

@@ -0,0 +1,5 @@
+from .gpt import Gpt
+from .llm import Llm
+from .llm_provider import LlmProvider
+
+__all__ = ["Gpt", "Llm", "LlmProvider"]

pycaps/ai/gpt.py

@@ -0,0 +1,35 @@
+from pycaps.ai.llm import Llm
+import os
+
+class Gpt(Llm):
+
+    OPENAI_API_KEY_NAME = "PYCAPS_OPENAI_API_KEY"
+
+    def __init__(self):
+        self._client = None
+
+    def send_message(self, prompt: str, model: str = "gpt-4.1-mini") -> str:
+        return self._get_client().responses.create(model=model, input=prompt).output_text
+    
+    def is_enabled(self) -> bool:
+        return os.getenv(self.OPENAI_API_KEY_NAME) is not None
+
+    def _get_client(self):
+        try:
+            from openai import OpenAI
+
+            if self._client:
+                return self._client
+
+            self._client = OpenAI(api_key=os.getenv(self.OPENAI_API_KEY_NAME))
+            return self._client
+        except ImportError:
+            raise ImportError(
+                "OpenAI API not found. "
+                "Please install it with: pip install openai"
+            )
+        except Exception as e:
+            raise RuntimeError(
+                f"Error initializing OpenAI client: {e}\n\n"
+                "Please ensure you have authenticated correctly via PYCAPS_OPENAI_API_KEY."
+            )

pycaps/ai/llm.py

@@ -0,0 +1,11 @@
+from abc import ABC, abstractmethod
+
+class Llm(ABC):
+
+    @abstractmethod
+    def send_message(self, message: str, model: str) -> str:
+        pass
+
+    @abstractmethod
+    def is_enabled(self) -> bool:
+        pass

pycaps/ai/llm_provider.py

@@ -0,0 +1,16 @@
+from typing import Optional
+from .llm import Llm
+from .gpt import Gpt
+
+class LlmProvider:
+    _llm: Optional[Llm] = None
+
+    @staticmethod
+    def get() -> Llm:
+        if LlmProvider._llm is None:
+            LlmProvider._llm = Gpt()
+        return LlmProvider._llm
+    
+    @staticmethod
+    def set(llm: Llm):
+        LlmProvider._llm = llm

pycaps/animation/__init__.py

@@ -0,0 +1,31 @@
+# src/pycaps/animator/__init__.py
+
+from .builtin import *
+from .definitions import Transformer, OvershootConfig, Direction
+from .primitive_animation import PrimitiveAnimation
+from .preset_animation import PresetAnimation
+from .animation import Animation
+from .element_animator import ElementAnimator
+
+__all__ = [
+    "Animation",
+    "PrimitiveAnimation",
+    "PresetAnimation",
+    "ElementAnimator",
+    "Transformer",
+    "OvershootConfig",
+    "Direction",
+    "SlideInPrimitive",
+    "ZoomInPrimitive",
+    "PopInPrimitive",
+    "FadeInPrimitive",
+    "FadeIn",
+    "FadeOut",
+    "PopIn",
+    "PopOut",
+    "PopInBounce",
+    "SlideIn",
+    "SlideOut",
+    "ZoomIn",
+    "ZoomOut",
+]

pycaps/animation/animation.py

@@ -0,0 +1,11 @@
+from pycaps.common import WordClip, ElementType
+from abc import ABC, abstractmethod
+
+class Animation(ABC):
+    def __init__(self, duration: float, delay: float = 0.0) -> None:
+        self._duration: float = duration
+        self._delay: float = delay
+
+    @abstractmethod
+    def run(self, clip: WordClip, offset: float, what: ElementType) -> None:
+        pass

pycaps/animation/builtin/__init__.py

@@ -0,0 +1,18 @@
+from .primitive import *
+from .preset import *
+
+__all__ = [
+    "FadeIn",
+    "FadeOut",
+    "SlideIn",
+    "SlideOut",
+    "ZoomIn",
+    "ZoomOut",
+    "PopIn",
+    "PopOut",
+    "PopInBounce",
+    "FadeInPrimitive",
+    "PopInPrimitive",
+    "ZoomInPrimitive",
+    "SlideInPrimitive",
+]

pycaps/animation/builtin/preset/__init__.py

@@ -0,0 +1,21 @@
+from .fade_in import FadeIn
+from .fade_out import FadeOut
+from .pop_in import PopIn
+from .pop_out import PopOut
+from .pop_in_bounce import PopInBounce
+from .slide_in import SlideIn
+from .slide_out import SlideOut
+from .zoom_in import ZoomIn
+from .zoom_out import ZoomOut
+
+__all__ = [
+    "FadeIn",
+    "FadeOut",
+    "PopIn",
+    "PopOut",
+    "PopInBounce",
+    "SlideIn",
+    "SlideOut",
+    "ZoomIn",
+    "ZoomOut",
+]

pycaps/animation/builtin/preset/fade_in.py

@@ -0,0 +1,17 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import FadeInPrimitive
+from typing import List
+
+class FadeIn(PresetAnimation):
+
+    def __init__(self, duration: float = 0.2, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            FadeInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+            )
+        ]

pycaps/animation/builtin/preset/fade_out.py

@@ -0,0 +1,19 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from typing import List
+from ...definitions import Transformer
+from ..primitive import FadeInPrimitive
+
+class FadeOut(PresetAnimation):
+
+    def __init__(self, duration: float = 0.2, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            FadeInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                transformer=Transformer.INVERT
+            )
+        ]

pycaps/animation/builtin/preset/pop_in.py

@@ -0,0 +1,22 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import PopInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import OvershootConfig
+
+class PopIn(PresetAnimation):
+
+    def __init__(self, duration: float = 0.3, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            PopInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                overshoot=OvershootConfig(),
+                min_scale=0.5,
+                init_scale=0.5
+            ),
+            FadeInPrimitive(duration=self._duration, delay=self._delay)
+        ]

pycaps/animation/builtin/preset/pop_in_bounce.py

@@ -0,0 +1,20 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import PopInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import OvershootConfig
+
+class PopInBounce(PresetAnimation):
+
+    def __init__(self, duration: float = 0.4, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            PopInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                overshoot=OvershootConfig()
+            ),
+            FadeInPrimitive(duration=self._duration*0.2, delay=self._delay)
+        ]

pycaps/animation/builtin/preset/pop_out.py

@@ -0,0 +1,22 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import PopInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import Transformer
+
+class PopOut(PresetAnimation):
+
+    def __init__(self, duration: float = 0.2, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            PopInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                transformer=Transformer.INVERT,
+                init_scale=0.2,
+                min_scale=0.2
+            ),
+            FadeInPrimitive(duration=self._duration, delay=self._delay, transformer=Transformer.INVERT)
+        ]

pycaps/animation/builtin/preset/slide_in.py

@@ -0,0 +1,25 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import SlideInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import Direction, OvershootConfig
+
+class SlideIn(PresetAnimation):
+
+    def __init__(self, direction: Direction = Direction.LEFT, duration: float = 0.3, delay: float = 0.0) -> None:
+        super().__init__(duration, delay)
+        self._direction: Direction = direction
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            SlideInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                direction=self._direction,
+                overshoot=OvershootConfig()
+            ),
+            FadeInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+            )
+        ]

pycaps/animation/builtin/preset/slide_out.py

@@ -0,0 +1,26 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import SlideInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import Transformer, Direction
+
+class SlideOut(PresetAnimation):
+
+    def __init__(self, direction: Direction = Direction.RIGHT, duration: float = 0.3, delay: float = 0.0) -> None:
+        super().__init__(duration, delay)
+        self._direction: Direction = direction
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            SlideInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                direction=self._direction,
+                transformer=Transformer.INVERT
+            ),
+            FadeInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                transformer=Transformer.INVERT
+            )
+        ]

pycaps/animation/builtin/preset/zoom_in.py

@@ -0,0 +1,24 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import ZoomInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import OvershootConfig, Transformer
+
+class ZoomIn(PresetAnimation):
+
+    def __init__(self, duration: float = 0.3, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            ZoomInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                overshoot=OvershootConfig(),
+                transformer=Transformer.EASE_OUT
+            ),
+            FadeInPrimitive(
+                duration=self._duration*0.5,
+                delay=self._delay,
+            )
+        ]

pycaps/animation/builtin/preset/zoom_out.py

@@ -0,0 +1,25 @@
+from ...animation import Animation
+from ...preset_animation import PresetAnimation
+from ..primitive import ZoomInPrimitive, FadeInPrimitive
+from typing import List
+from ...definitions import Transformer
+
+class ZoomOut(PresetAnimation):
+
+    def __init__(self, duration: float = 0.3, delay: float = 0.0):
+        super().__init__(duration, delay)
+
+    def _build_animations(self) -> List[Animation]:
+        return [
+            ZoomInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                init_scale=0.2,
+                transformer=Transformer.INVERT
+            ),
+            FadeInPrimitive(
+                duration=self._duration,
+                delay=self._delay,
+                transformer=Transformer.INVERT
+            )
+        ]

pycaps/animation/builtin/primitive/__init__.py

@@ -0,0 +1,11 @@
+from .fade_in_primitive import FadeInPrimitive
+from .pop_in_primitive import PopInPrimitive
+from .zoom_in_primitive import ZoomInPrimitive
+from .slide_in_primitive import SlideInPrimitive
+
+__all__ = [
+    "FadeInPrimitive",
+    "PopInPrimitive",
+    "ZoomInPrimitive",
+    "SlideInPrimitive",
+]

pycaps/animation/builtin/primitive/fade_in_primitive.py

@@ -0,0 +1,6 @@
+from ...primitive_animation import PrimitiveAnimation
+from pycaps.common import WordClip
+
+class FadeInPrimitive(PrimitiveAnimation):
+    def _apply_animation(self, clip: WordClip, offset: float) -> None:
+        self._apply_opacity(clip, offset, lambda t: t)

pycaps/animation/builtin/primitive/pop_in_primitive.py

@@ -0,0 +1,64 @@
+from typing import Tuple, Callable, Optional
+from ...definitions import Transformer, OvershootConfig
+from ...primitive_animation import PrimitiveAnimation
+from pycaps.common import WordClip
+from pycaps.layout import LayoutUtils
+
+class PopInPrimitive(PrimitiveAnimation):
+    def __init__(
+        self,
+        duration: float,
+        delay: float = 0.0,
+        transformer: Callable[[float], float] = Transformer.LINEAR,
+        init_scale: float = 0.7,
+        min_scale: float = 0.3,
+        min_scale_at: float = 0.5,
+        overshoot: Optional[OvershootConfig] = None,
+    ) -> None:
+        super().__init__(duration, delay, transformer)
+        self._init_scale: float = init_scale
+        self._min_scale: float = min_scale
+        self._min_scale_at: float = min_scale_at
+        self._overshoot: Optional[OvershootConfig] = overshoot
+
+        if self._overshoot is not None and self._min_scale_at >= self._overshoot.peak_at:
+            raise ValueError("min_scale_at must be less than overshoot.peak_at")
+
+    def _apply_animation(self, clip: WordClip, offset: float) -> None:
+        group_center = LayoutUtils.get_clip_container_center(clip, self._what)
+        word_original_width = clip.layout.size.width
+        word_original_height = clip.layout.size.height
+        word_final_center_x = clip.layout.position.x + word_original_width / 2
+        word_final_center_y = clip.layout.position.y + word_original_height / 2
+    
+        def get_size_factor(t: float) -> float:
+            peak_at = self._overshoot.peak_at if self._overshoot is not None else 1.0
+            overshoot_scale = 1 + self._overshoot.amount if self._overshoot is not None else 1.0
+
+            if t < self._min_scale_at:
+                progress = t / self._min_scale_at
+                return self._init_scale + (self._min_scale - self._init_scale) * progress
+            elif self._min_scale_at < t < peak_at:
+                progress = (t - self._min_scale_at) / (peak_at - self._min_scale_at)
+                return self._min_scale + (overshoot_scale - self._min_scale) * progress
+            elif peak_at < t < 1.0:
+                progress = (t - peak_at) / (1.0 - peak_at) if peak_at != 1.0 else 1.0
+                return overshoot_scale + (1.0 - overshoot_scale) * progress
+            else:
+                return 1.0
+
+        def get_position(t: float) -> Tuple[float, float]:
+            scale = get_size_factor(t)
+            current_width = word_original_width * scale
+            current_height = word_original_height * scale
+
+            current_center_x = group_center[0] + (word_final_center_x - group_center[0]) * t
+            current_center_y = group_center[1] + (word_final_center_y - group_center[1]) * t
+
+            final_x = current_center_x - (current_width / 2)
+            final_y = current_center_y - (current_height / 2)
+            
+            return (final_x, final_y)
+
+        self._apply_size(clip, offset, get_size_factor)
+        self._apply_position(clip, offset, get_position)

pycaps/animation/builtin/primitive/slide_in_primitive.py

@@ -0,0 +1,54 @@
+from ...primitive_animation import PrimitiveAnimation
+from ...definitions import Direction, OvershootConfig, Transformer
+from pycaps.common import WordClip
+from typing import Tuple, Callable, Optional
+
+class SlideInPrimitive(PrimitiveAnimation):
+    def __init__(
+            self,
+            duration: float,
+            delay: float = 0.0,
+            transformer: Callable[[float], float] = Transformer.LINEAR,
+            direction: Direction = Direction.LEFT,
+            distance: float = 100,
+            overshoot: Optional[OvershootConfig] = None,
+        ) -> None:
+        super().__init__(duration, delay, transformer)
+        self._direction: Direction = direction
+        self._distance: float = distance
+        self._overshoot: Optional[OvershootConfig] = overshoot
+
+    def _apply_animation(self, clip: WordClip, offset: float) -> None:
+        final_pos = clip.layout.position
+
+        def get_displacement(t: float) -> float:
+            if self._overshoot is None:
+                return self._distance * (t-1)
+            
+            overshoot_distance = self._distance * self._overshoot.amount
+            if t < self._overshoot.peak_at:
+                progress = t / self._overshoot.peak_at
+                start_offset = -(self._distance)
+                target_offset = overshoot_distance
+                return start_offset + (target_offset - start_offset) * progress
+            else:
+                progress = (t - self._overshoot.peak_at) / (1.0 - self._overshoot.peak_at)
+                start_offset = overshoot_distance
+                target_offset = 0
+                return start_offset + (target_offset - start_offset) * progress
+                
+        def get_position(t: float) -> Tuple[float, float]:
+            current_displacement = get_displacement(t)
+
+            if self._direction == Direction.LEFT:
+                return final_pos.x + current_displacement, final_pos.y
+            elif self._direction == Direction.RIGHT:
+                return final_pos.x - current_displacement, final_pos.y
+            elif self._direction == Direction.UP:
+                return final_pos.x, final_pos.y + current_displacement
+            elif self._direction == Direction.DOWN:
+                return final_pos.x, final_pos.y - current_displacement
+            return final_pos.x, final_pos.y
+
+
+        self._apply_position(clip, offset, get_position)

pycaps/animation/builtin/primitive/zoom_in_primitive.py

@@ -0,0 +1,64 @@
+from pycaps.common import WordClip
+from pycaps.layout import LayoutUtils
+from typing import Tuple, Callable, Optional
+from ...definitions import Transformer, OvershootConfig
+from ...primitive_animation import PrimitiveAnimation
+
+# TODO: it has an error while size is being animated, it's probably a precision error (because of using floats for the size in the scale)
+# To notice it, you need to use a color background for a whole line, and run this animation over the line.
+class ZoomInPrimitive(PrimitiveAnimation):
+
+    def __init__(
+        self,
+        duration: float,
+        delay: float = 0.0,
+        transformer: Callable[[float], float] = Transformer.LINEAR,
+        init_scale: float = 0.5,
+        overshoot: Optional[OvershootConfig] = None,
+    ) -> None:
+        super().__init__(duration, delay, transformer)
+        self._init_scale: float = init_scale
+        self._overshoot: Optional[OvershootConfig] = overshoot
+
+    def _apply_animation(self, clip: WordClip, offset: float) -> None:
+        group_center = LayoutUtils.get_clip_container_center(clip, self._what)
+        word_final_center = (
+            clip.layout.position.x + clip.layout.size.width / 2,
+            clip.layout.position.y + clip.layout.size.height / 2
+        )
+        relative_pos_vector = (
+            word_final_center[0] - group_center[0],
+            word_final_center[1] - group_center[1]
+        )
+
+        def get_size_factor(t: float) -> float:
+            if self._overshoot is None:
+                return self._init_scale + (1.0 - self._init_scale) * t
+            
+            if t < self._overshoot.peak_at:
+                progress = t / self._overshoot.peak_at
+                start_offset = self._init_scale
+                target_offset = 1 + self._overshoot.amount
+                return start_offset + (target_offset - start_offset) * progress
+            
+            progress = (t - self._overshoot.peak_at) / (1.0 - self._overshoot.peak_at)
+            start_offset = 1 + self._overshoot.amount
+            target_offset = 1
+            return start_offset - (start_offset - target_offset) * progress
+
+        def get_position(t: float) -> Tuple[float, float]:
+            progress = get_size_factor(t)
+            
+            current_width = clip.layout.size.width * progress
+            current_height = clip.layout.size.height * progress
+
+            current_center_x = group_center[0] + (relative_pos_vector[0] * progress)
+            current_center_y = group_center[1] + (relative_pos_vector[1] * progress)
+
+            final_x = current_center_x - (current_width / 2)
+            final_y = current_center_y - (current_height / 2)
+            
+            return (final_x, final_y)
+
+        self._apply_position(clip, offset, get_position)
+        self._apply_size(clip, offset, get_size_factor)

pycaps/animation/definitions.py

@@ -0,0 +1,22 @@
+from enum import Enum
+from dataclasses import dataclass
+from pydantic import BaseModel, ConfigDict
+
+class Direction(str, Enum):
+    LEFT = "left"
+    RIGHT = "right"
+    UP = "up"
+    DOWN = "down"
+
+class OvershootConfig(BaseModel):
+    model_config = ConfigDict(frozen=True)
+    
+    amount: float = 0.1
+    peak_at: float = 0.7
+
+class Transformer:
+    LINEAR = lambda t: t
+    EASE_IN = lambda t: t**2
+    EASE_OUT = lambda t: 1 - (1 - t)**2
+    EASE_IN_OUT = lambda t: t**2 * (3 - 2 * t)
+    INVERT = lambda t: 1 - t

pycaps/animation/element_animator.py

@@ -0,0 +1,52 @@
+from typing import Optional, List
+from pycaps.common import ElementType, EventType, Document, WordClip
+from pycaps.tag import TagCondition
+from pycaps.selector import WordClipSelector
+from .animation import Animation
+
+class ElementAnimator:
+
+    def __init__(self, animation: Animation, when: EventType, what: ElementType, tag_condition: Optional[TagCondition] = None) -> None:
+        self._animation: Animation = animation
+        self._when: EventType = when
+        self._what: ElementType = what
+        self._tag_condition: Optional[TagCondition] = tag_condition
+
+    def run(self, document: Document) -> None:
+        clips = self._filter_clips(document)
+        for clip in clips:
+            offset = self.__get_time_offset(clip)
+            self._animation.run(clip, offset, self._what)
+
+    def _filter_clips(self, document: Document) -> List[WordClip]:
+        selector = WordClipSelector().filter_by_time(self._when, self._what, self._animation._duration, self._animation._delay)
+        if self._tag_condition:
+            selector = selector.filter_by_tag(self._tag_condition)
+        return selector.select(document)
+
+    def __get_time_offset(self, clip: WordClip) -> float:
+        if self._when == EventType.ON_NARRATION_STARTS:
+            return self.__get_on_start_offset(clip)
+        elif self._when == EventType.ON_NARRATION_ENDS:
+            return self.__get_on_end_offset(clip)
+    
+    def __get_on_start_offset(self, clip: WordClip) -> float:
+        start_time = 0
+        if self._what == ElementType.WORD:
+            start_time = clip.get_word().time.start
+        elif self._what == ElementType.LINE:
+            start_time = clip.get_line().time.start
+        elif self._what == ElementType.SEGMENT:
+            start_time = clip.get_segment().time.start
+
+        return clip.media_clip.start - start_time - self._animation._delay
+
+    def __get_on_end_offset(self, clip: WordClip) -> float:
+        end_time = 0
+        if self._what == ElementType.WORD:
+            end_time = clip.get_word().time.end
+        elif self._what == ElementType.LINE:
+            end_time = clip.get_line().time.end
+        elif self._what == ElementType.SEGMENT:
+            end_time = clip.get_segment().time.end
+        return -(end_time - self._animation._duration - self._animation._delay - clip.media_clip.start)