hooks.py

​

Overview

​

Key Functions

​

add_hook_to_video

def add_hook_to_video(
    video_path: str,
    text: str,
    output_path: str,
    position: str = "top",
    font_scale: float = 1.0
) -> bool

• video_path (str): Path to input video file
• text (str): Hook text to overlay (supports newlines \n for manual breaks)
• output_path (str): Path for output video
• position (str): Vertical position - "top", "center", or "bottom" (default: "top")
• font_scale (float): Font size multiplier (default: 1.0)

• bool: True if successful (raises exception on failure)

1. Probes video dimensions using ffprobe
2. Generates hook image via create_hook_image()
3. Calculates overlay position based on position parameter
4. Uses FFmpeg overlay filter to composite text onto video
5. Cleans up temporary image file

ffmpeg -y \
  -i video.mp4 \
  -i hook_overlay.png \
  -filter_complex "[0:v][1:v]overlay=X:Y" \
  -c:a copy \
  -c:v libx264 -preset fast -crf 22 \
  output.mp4

​

create_hook_image

def create_hook_image(
    text: str,
    target_width: int,
    output_image_path: str = "hook_overlay.png",
    font_scale: float = 1.0
) -> tuple[str, int, int]

• text (str): Text content (supports \n for manual line breaks)
• target_width (int): Maximum box width (typically 90% of video width)
• output_image_path (str): Path to save PNG image (default: "hook_overlay.png")
• font_scale (float): Font size multiplier (default: 1.0)

• tuple of:
  • img_path (str): Path to generated image
  • box_width (int): Final box width in pixels
  • box_height (int): Final box height in pixels

• Font: Noto Serif Bold (downloaded automatically)
• Font Size: target_width * 0.05 * font_scale (approx 5% of video width)
• Text Color: Black
• Box Color: White with 94% opacity (RGBA(255, 255, 255, 240))
• Padding: 30px horizontal, 25px vertical
• Line Spacing: 20px
• Corner Radius: 20px
• Shadow: 5px offset, 10px blur, 39% opacity (RGBA(0, 0, 0, 100))

• Pixel-based wrapping using Pillow’s textbbox()
• Max text width: target_width - 60px (accounting for padding)
• Respects manual newlines (\n)
• Minimum box width: 30% of target_width

​

download_font_if_needed

def download_font_if_needed() -> None

• URL: https://github.com/googlefonts/noto-fonts/raw/main/hinted/ttf/NotoSerif/NotoSerif-Bold.ttf
• Local Path: fonts/NotoSerif-Bold.ttf
• Fallback: Uses Pillow’s default font if download fails

​

Constants

FONT_URL = "https://github.com/googlefonts/noto-fonts/raw/main/hinted/ttf/NotoSerif/NotoSerif-Bold.ttf"
FONT_DIR = "fonts"
FONT_PATH = "fonts/NotoSerif-Bold.ttf"

​

Font Rendering System

1. Font Loading: TrueType font with dynamic sizing
2. Text Measurement: Pixel-accurate bounding box calculations
3. Smart Wrapping: Word-by-word wrapping to maximize readability
4. Layer Composition:
   • Shadow layer (blurred)
   • White box (sharp, overlaid on shadow)
   • Black text (overlaid on box)

​

Example Usage

​

Basic Hook

from hooks import add_hook_to_video

add_hook_to_video(
    video_path="clip_1.mp4",
    text="POV: You realized the secret",
    output_path="clip_1_hooked.mp4",
    position="top"
)

​

Multiline Hook

add_hook_to_video(
    video_path="clip_2.mp4",
    text="This changes everything\nWatch until the end",
    output_path="clip_2_hooked.mp4",
    position="center",
    font_scale=1.2  # 20% larger font
)

​

Large Bottom Hook

add_hook_to_video(
    video_path="clip_3.mp4",
    text="Wait for it...",
    output_path="clip_3_hooked.mp4",
    position="bottom",
    font_scale=1.5  # 50% larger
)

​

Visual Specification

​

Box Layout

┌─────────────────────────────────────┐
│                                     │ ← 25px padding
│    This is the hook text that      │
│    automatically wraps to fit      │ ← 20px line spacing
│    within the target width         │
│                                     │ ← 25px padding
└─────────────────────────────────────┘
  ↑                                 ↑
  30px                              30px
  padding                           padding

​

Shadow Effect

     ┌─────────┐
     │  Box    │
  ┌──┴─────────┴──┐
  │    Shadow     │ ← 5px offset, 10px blur
  └───────────────┘

​

Position Logic

# X position (always centered)
overlay_x = (video_width - box_width) // 2

# Y position (varies by parameter)
if position == "top":
    overlay_y = int(video_height * 0.20)  # 20% from top
elif position == "center":
    overlay_y = (video_height - box_height) // 2
else:  # bottom
    overlay_y = int(video_height * 0.70)  # 70% from top

​

Dependencies

• Pillow (PIL): Image generation and text rendering
  • Image: Canvas creation
  • ImageDraw: Drawing shapes and text
  • ImageFont: TrueType font loading
  • ImageFilter: Gaussian blur for shadows
• ffmpeg: Video overlay composition (subprocess)
• ffprobe: Video dimension probing
• urllib.request: Font file download