sosi-call 0.1.5

Generate a pixel-art 'call style' avatar video reacting to audio.

sosi-call

Generate a pixel-art “call style” avatar video reacting to audio: a circular avatar + a pulsing ring synced to voice amplitude.

• ✅ Works with audio like .wav, .mp3, .ogg, etc. (whatever your environment can decode)
• ✅ Output: square MP4 (default 1080×1080), black background, pixel-art look
• ✅ Includes both Python API and a CLI

Note: This package uses MoviePy, which relies on FFmpeg being available in your system PATH.

Demo video

Open: docs/demo3.mp4

---

Install

pip install sosi-call

FFmpeg (required)

If you don’t have ffmpeg installed:

Ubuntu/Debian

sudo apt update && sudo apt install -y ffmpeg

macOS (Homebrew)

brew install ffmpeg

---

Quickstart (Python)

from sosi_call import render_call_video, RenderConfig

cfg = RenderConfig(
    size=1080,  # output resolution (square)
    low=240,    # internal pixel-art resolution (lower=faster+more chunky)
    fps=30,
    gain=3.2,   # sensitivity
    gamma=0.45, # boosts quieter voice
)

render_call_video(
    avatar_path="perfil.jpeg",
    audio_path="demo.ogg",
    out_path="sosi_call.mp4",
    cfg=cfg,
)

---

CLI usage

sosi-call --avatar perfil.jpeg --audio demo.ogg --out sosi_call.mp4

Common tweaks:

# More pixelated + faster
sosi-call --avatar perfil.jpeg --audio demo.ogg --out out.mp4 --low 180

# Less pixelated (smoother circle) but slower
sosi-call --avatar perfil.jpeg --audio demo.ogg --out out.mp4 --low 320

# More reactive ring
sosi-call --avatar perfil.jpeg --audio demo.ogg --out out.mp4 --gain 4.0 --gamma 0.45

---

Output and how to use it in editing

The generated video is a square MP4 with a pure black background, ideal for compositing:

• Put it as a layer above your screen recording
• Remove the black background using:
  • Screen/Add blend mode, or
  • Luma Key (key out dark pixels)

---

Configuration notes

• size: final output (default 1080). Always square.
• low: internal render resolution. Controls pixelation + speed.
  • 180 = very chunky + fast
  • 240 = balanced (default)
  • 320 = less jagged, slower
• gain / gamma: controls sensitivity to voice amplitude.
  • Increase gain if it moves too little
  • Lower gamma (< 1) to amplify quieter audio

---

Development (uv)

uv sync
uv run python -c "from sosi_call import render_call_video; print('ok')"

Editable install:

uv pip install -e .

---

License

MIT