Metadata-Version: 2.5
Name: tivalvideo-offline
Version: 0.2.0
Summary: Create narrated and auto-typing videos completely offline
Project-URL: Homepage, https://github.com/tivalsdeveloper-oss/tivalvideo-offline
Project-URL: Documentation, https://github.com/tivalsdeveloper-oss/tivalvideo-offline#readme
Project-URL: Repository, https://github.com/tivalsdeveloper-oss/tivalvideo-offline
Project-URL: Issues, https://github.com/tivalsdeveloper-oss/tivalvideo-offline/issues
Author: Tivalsdeveloper
License: MIT
License-File: LICENSE
Keywords: ffmpeg,offline,piper,shorts,text-to-speech,video
Requires-Python: >=3.9
Requires-Dist: imageio-ffmpeg>=0.5.1
Requires-Dist: pillow>=10.0
Requires-Dist: piper-tts>=1.3.0
Requires-Dist: platformdirs>=4.0
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.8; extra == 'dev'
Description-Content-Type: text/markdown

# TivalVideo Offline 0.2.0

Create narrated vertical Shorts or landscape videos from images, entirely offline after the first setup. TivalVideo uses a managed FFmpeg executable for video rendering and Piper for local AI narration.

Version 0.2.0 adds auto-typing text videos, recorded audio, background music, four built-in backgrounds, and custom background images.

## Install

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install .
```

`pip` automatically installs FFmpeg and Piper dependencies. The first video automatically downloads the approximately 61 MB Piper voice model, or you can prepare it explicitly:

```bash
tivalvideo setup
```

After setup, disconnect from the internet and create videos offline.

## Python example

```python
from tivalvideo import create_video

create_video(
    images=["lesson1.png", "lesson2.png", "lesson3.png"],
    narration="Learn TivalTube with these simple examples.",
    output="tivaltube-short.mp4",
)
```

## Auto-typing video

Create a complete Short without supplying lesson images:

```python
from tivalvideo import create_video

create_video(
    typing_text="Welcome to my Python lesson!",
    narration="Welcome to my Python lesson.",
    background="ocean",
    output="typing-short.mp4",
)
```

Built-in background choices are `midnight`, `ocean`, `sunset`, and `paper`.

Use your own background image:

```python
create_video(
    typing_text="Learn Python step by step",
    audio="my-recorded-voice.mp3",
    background_image="my-background.jpg",
    output="custom-short.mp4",
)
```

## Recorded voice and music

Use recorded voice instead of AI narration and optionally mix in music:

```python
create_video(
    images=["lesson1.png", "lesson2.png"],
    audio="voice.wav",
    music="background.mp3",
    output="lesson.mp4",
)
```

Do not pass both `narration` and `audio`; they are two alternative voice sources.

## Terminal example

Create `narration.txt`, then run:

```bash
tivalvideo create \
  lesson1.png lesson2.png lesson3.png \
  --narration narration.txt \
  --output short.mp4
```

Use `--landscape` for a 1920×1080 video:

```bash
tivalvideo create *.png -n narration.txt -o youtube.mp4 --landscape
```

## Features

- 1080×1920 TikTok and YouTube Shorts
- 1920×1080 landscape videos
- Offline Piper AI narration
- Managed FFmpeg binary—no `apt install ffmpeg` required
- Blurred full-screen background with centred images
- Automatic fade transitions
- H.264 video and AAC audio
- Automatic voice-model caching
- Auto-typing text animation
- MP3/WAV recorded voice and background music
- Built-in and user-provided auto-typing backgrounds
- Python API and terminal command

## Notes

- The first setup requires internet access for the voice download.
- Generated videos work from local image files and text only.
- Keep the voice model cached to remain fully offline.

Powered by tivalsdeveloper.
