Metadata-Version: 2.4
Name: araboja-shorts
Version: 0.2.0
Summary: Automated Korean short-form history videos: topic selection, Korean narration, TTS, and 1080x1920 ffmpeg rendering.
Author-email: Kim hyosung <drchamchi2@gmail.com>
License: MIT License
        
        Copyright (c) 2026 Kim hyosung
        
        Permission is hereby granted, free of charge, to any person obtaining a copy
        of this software and associated documentation files (the "Software"), to deal
        in the Software without restriction, including without limitation the rights
        to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
        copies of the Software, and to permit persons to whom the Software is
        furnished to do so, subject to the following conditions:
        
        The above copyright notice and this permission notice shall be included in all
        copies or substantial portions of the Software.
        
        THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
        IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
        FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
        AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
        LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
        OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
        SOFTWARE.
        
Project-URL: Homepage, https://github.com/drchamchi2-oss/araboja-shorts
Project-URL: Issues, https://github.com/drchamchi2-oss/araboja-shorts/issues
Project-URL: Changelog, https://github.com/drchamchi2-oss/araboja-shorts/blob/main/CHANGELOG.md
Keywords: shorts,video,tts,ffmpeg,korean,youtube,automation
Classifier: Development Status :: 3 - Alpha
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Multimedia :: Video
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: openai>=1.0.0
Requires-Dist: Pillow>=12.2.0
Requires-Dist: python-dotenv>=1.2.2
Requires-Dist: requests>=2.31.0
Dynamic: license-file

# araboja-shorts (아라보자 쇼츠)

[![Python CI](https://github.com/drchamchi2-oss/araboja-shorts/actions/workflows/python-ci.yml/badge.svg)](https://github.com/drchamchi2-oss/araboja-shorts/actions/workflows/python-ci.yml)
[![CodeQL](https://github.com/drchamchi2-oss/araboja-shorts/actions/workflows/codeql.yml/badge.svg)](https://github.com/drchamchi2-oss/araboja-shorts/actions/workflows/codeql.yml)
[![License: MIT](https://img.shields.io/badge/License-MIT-blue.svg)](LICENSE)
[![Release downloads](https://img.shields.io/github/downloads/drchamchi2-oss/araboja-shorts/total)](https://github.com/drchamchi2-oss/araboja-shorts/releases)

`araboja-shorts` is a Python pipeline for generating Korean short-form videos about ancient artifacts, archaeological sites, and ancient-civilization mysteries — from topic selection to a finished, subtitled 1080x1920 video.

> Formerly published as `shorts_test`. Renamed after the original araboja shorts project it grew out of; old links redirect here.

The script builds a roughly 60-second vertical video by selecting a topic from public web sources, drafting a Korean narration with OpenAI, collecting public-source imagery, generating TTS audio, rendering scenes with ffmpeg, burning subtitles, and cleaning intermediate files.

```mermaid
flowchart LR
    A[Topic selection<br/>Wikipedia / trends] --> B[Korean script<br/>OpenAI]
    B --> C[Images<br/>Wikimedia Commons]
    B --> D[TTS narration<br/>OpenAI]
    C --> E[ffmpeg render<br/>1080x1920 + subtitles + BGM]
    D --> E
    E --> F[final.mp4<br/>+ attribution metadata]
```

## Demo

A sample araboja shorts video, in the format this pipeline produces:

[![Sample araboja shorts video](https://img.youtube.com/vi/irgscHEXidA/maxresdefault.jpg)](https://youtube.com/shorts/irgscHEXidA)

## What It Does

- Selects archaeology and ancient-mystery topics from Wikipedia and trend sources.
- Generates a Korean short-form script with scene-level narration.
- Collects images from Wikimedia Commons, with optional Pexels and Pixabay fallback.
- Creates OpenAI TTS narration.
- Renders 1080x1920 video scenes with title overlays, zoom/pan motion, subtitles, and BGM.
- Keeps the final output, generated script, and source images while cleaning temporary media files.

## Requirements

- Python 3.10+
- ffmpeg and ffprobe available on `PATH`, or pass `--ffmpeg_path`
- An OpenAI API key
- A local BGM file at `bgm_no_attrib/mystery.mp3`
- Optional API keys for Pexels and Pixabay image fallback

Install as a package (provides the `araboja-shorts` command):

```bash
python -m pip install git+https://github.com/drchamchi2-oss/araboja-shorts
```

Or from a local checkout:

```bash
python -m pip install .
```

Or install only the runtime dependencies:

```bash
python -m pip install -r requirements.txt
```

For development and CI-equivalent checks:

```bash
python -m pip install -r requirements-dev.txt
```

Create a local `.env` file from the example:

```bash
copy .env.example .env
```

Then edit `.env` and add your own keys. Do not commit `.env`.

## Usage

```bash
araboja-shorts run --verbose
```

Or run the module directly from a source checkout:

```bash
python main_gpt.py run --verbose
```

To check topic and script generation without rendering video, audio, or images:

```bash
python main_gpt.py run --dry_run --verbose
```

If ffmpeg is not on `PATH`:

```bash
python main_gpt.py run --ffmpeg_path C:\ffmpeg\bin\ffmpeg.exe --verbose
```

Generated files are written under `out_araboza/`. Full runs write `final.mp4`, `script.json`, `media_attribution.json`, and selected source images. Dry runs write `script.json` and `media_attribution.json`.

## Development Checks

Run the local checks before opening a pull request:

```bash
python -m py_compile main_gpt.py shorts_media.py shorts_rendering.py scripts/doctor.py
python -m pytest
python -m bandit -r main_gpt.py shorts_media.py shorts_rendering.py scripts -x tests -ll
python -m pip_audit -r requirements.txt
```

The GitHub Actions workflow runs the same syntax, test, static security, and dependency-audit checks on pull requests and pushes to `main`.

To check local runtime prerequisites before generating a video:

```bash
python scripts/doctor.py
```

## Configuration

Required environment variable:

```text
OPENAI_API_KEY=your_openai_api_key
```

Optional environment variables:

```text
PEXELS_API_KEY=your_pexels_api_key
PIXABAY_API_KEY=your_pixabay_api_key
```

The repository intentionally does not include private keys, generated videos, local cache files, or BGM assets. Use only media that you are allowed to use and redistribute.

## Media And Licensing

Review `docs/media-and-licensing.md` before publishing generated videos or adding new media providers.

## Releases

Use `docs/release-checklist.md` before tagging a public release.

## Project Status

This project is early-stage OSS. The current goal is to make the single-file workflow reproducible, inspectable, and easier to maintain.

See `ROADMAP.md` for the current maintenance plan and near-term issues.

Known limitations:

- The script depends on live web APIs and external media sources.
- Output quality depends on available images, API responses, and local ffmpeg setup.
- BGM licensing is the user's responsibility.
- The generated script should be reviewed before publishing videos publicly.

## Security

Never commit API keys, `.env`, generated credentials, private logs, private datasets, or paid/proprietary media assets. See `SECURITY.md` for reporting guidance.

## Contributing

Focused issues and pull requests are welcome. See `CONTRIBUTING.md` before opening a PR.

## License

MIT. See `LICENSE`.
