{"id":42711169,"url":"https://github.com/semanticintent/semantic-foragecast-engine","last_synced_at":"2026-01-29T15:10:01.907Z","repository":{"id":323097385,"uuid":"1092113131","full_name":"semanticintent/semantic-foragecast-engine","owner":"semanticintent","description":"Procedural CLI pipeline for animating static mascots (e.g., AI fox) into lip-synced music videos. Offline Blender/Python magic: Beats → Phonemes → 2D/3D/Hybrid renders. Non-AI, modular, fast (3-12 mins/clip). Fork the forge!","archived":false,"fork":false,"pushed_at":"2025-12-20T19:53:31.000Z","size":28457,"stargazers_count":2,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-12-22T19:52:20.582Z","etag":null,"topics":["2d-animation","3d-rigging","blender3d","grease-pencil","lip-sync","music-video","offline-tools","procedural-animation","python-cli"],"latest_commit_sha":null,"homepage":"https://foragecast.dev","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/semanticintent.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-11-08T02:45:28.000Z","updated_at":"2025-12-20T19:53:35.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/semanticintent/semantic-foragecast-engine","commit_stats":null,"previous_names":["semanticintent/semantic-foragecast-engine"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/semanticintent/semantic-foragecast-engine","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semanticintent%2Fsemantic-foragecast-engine","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semanticintent%2Fsemantic-foragecast-engine/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semanticintent%2Fsemantic-foragecast-engine/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semanticintent%2Fsemantic-foragecast-engine/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/semanticintent","download_url":"https://codeload.github.com/semanticintent/semantic-foragecast-engine/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/semanticintent%2Fsemantic-foragecast-engine/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28880017,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-29T10:31:27.438Z","status":"ssl_error","status_checked_at":"2026-01-29T10:31:01.017Z","response_time":59,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["2d-animation","3d-rigging","blender3d","grease-pencil","lip-sync","music-video","offline-tools","procedural-animation","python-cli"],"created_at":"2026-01-29T15:10:01.203Z","updated_at":"2026-01-29T15:10:01.890Z","avatar_url":"https://github.com/semanticintent.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Semantic Foragecast Engine\n\n\u003e **Production-ready pipeline for audio-driven animation in Blender**\n\u003e\n\u003e A configuration-first, modular system demonstrating Blender automation, audio analysis integration, and headless rendering architecture.\n\n[![Python 3.9+](https://img.shields.io/badge/python-3.9+-blue.svg)](https://www.python.org/downloads/)\n[![Blender 4.0+](https://img.shields.io/badge/blender-4.0+-orange.svg)](https://www.blender.org/)\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)\n[![CI Status](https://github.com/semanticintent/semantic-foragecast-engine/workflows/CI%20-%20Semantic%20Foragecast%20Engine/badge.svg)](https://github.com/semanticintent/semantic-foragecast-engine/actions)\n[![Code Style: Black](https://img.shields.io/badge/code%20style-black-000000.svg)](https://github.com/psf/black)\n[![PRs Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](CONTRIBUTING.md)\n[![GitHub Stars](https://img.shields.io/github/stars/semanticintent/semantic-foragecast-engine?style=social)](https://github.com/semanticintent/semantic-foragecast-engine/stargazers)\n[![GitHub Issues](https://img.shields.io/github/issues/semanticintent/semantic-foragecast-engine)](https://github.com/semanticintent/semantic-foragecast-engine/issues)\n[![Documentation](https://img.shields.io/badge/docs-comprehensive-blue)](https://github.com/semanticintent/semantic-foragecast-engine#documentation)\n[![Featured](https://img.shields.io/badge/Featured-LinkedIn-0077B5)](https://foragecast.dev)\n\n---\n\n## What This Is\n\nA **fully functional pipeline** that transforms audio files into animated videos with synchronized lip movements, beat-reactive gestures, and timed lyrics — all driven by YAML configuration files instead of manual animation.\n\n**But more importantly**: A **technical demonstration** of production-ready Blender automation, showcasing:\n- ✅ Configuration-first architecture (no code changes for different outputs)\n- ✅ Headless rendering (cloud/container deployment ready)\n- ✅ Modular 4-phase pipeline with clean separation of concerns\n- ✅ Extensible plugin system (easy to add new animation modes)\n- ✅ Real-world performance benchmarks (tested in cloud environments)\n\n**Use Case**: Automated music video generation (lyric videos, podcasts, educational content)\n\n**Learning Value**: Demonstrates Blender Python API patterns, audio analysis integration, and pipeline architecture rarely documented elsewhere.\n\n---\n\n## Quick Start\n\n```bash\n# 1. Install dependencies\npip install -r requirements.txt\n\n# 2. Install Blender 4.0+ and FFmpeg\n# https://www.blender.org/download/\n# https://ffmpeg.org/download.html\n\n# 3. Run the pipeline with test config (renders in 4-6 minutes)\npython main.py --config config_ultra_fast.yaml\n\n# 4. Find output video\nls outputs/ultra_fast/ultra_fast.mp4\n```\n\n**Result**: 30-second video with animated mascot, lip sync, and lyrics.\n\n---\n\n## Documentation\n\n### For Developers\n\n- **[ARCHITECTURE.md](ARCHITECTURE.md)** - System design, data flow, extension points, deployment patterns\n- **[DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md)** - Step-by-step tutorials for adding modes, effects, and audio analysis\n- **[CASE_STUDIES.md](CASE_STUDIES.md)** - Real-world benchmarks, cloud rendering, performance optimization\n\n### For Users\n\n- **[TESTING_GUIDE.md](TESTING_GUIDE.md)** - Quality/speed configurations, testing workflow\n- **[AUTOMATED_LYRICS_GUIDE.md](AUTOMATED_LYRICS_GUIDE.md)** - Whisper integration for auto lyrics timing\n- **[POSITIONING_GUIDE.md](POSITIONING_GUIDE.md)** - Scene layout and debug visualization\n\n### Technical Docs\n\n- **[PIPELINE_TEST_EVALUATION.md](PIPELINE_TEST_EVALUATION.md)** - Complete test results from cloud environment\n- **[CROSS_PLATFORM_DEV_GUIDE.md](CROSS_PLATFORM_DEV_GUIDE.md)** - Windows/Linux development setup\n\n---\n\n## Architecture Overview\n\n```\n┌─────────────┐     ┌──────────────┐     ┌─────────────┐\n│   Phase 1   │────▶│   Phase 2    │────▶│   Phase 3   │\n│ Audio Prep  │     │  Rendering   │     │   Export    │\n│             │     │              │     │             │\n│ - Beats     │     │ - 2D/3D Mode │     │ - MP4       │\n│ - Phonemes  │     │ - Lip Sync   │     │ - H.264     │\n│ - Lyrics    │     │ - Gestures   │     │ - Audio Sync│\n└─────────────┘     └──────────────┘     └─────────────┘\n      ↓                     ↓                     ↓\n  prep_data.json       PNG frames             final.mp4\n```\n\n**Key Design Principles**:\n- **Separation of concerns**: Each phase independent, cacheable outputs\n- **Configuration over code**: YAML drives all behavior\n- **Extensibility**: Plugin-style animation modes\n- **Production-ready**: Headless rendering, error handling, validation\n\nSee [ARCHITECTURE.md](ARCHITECTURE.md) for complete system design.\n\n---\n\n## Features\n\n### Core Pipeline (4 Phases - All Complete ✅)\n\n**Phase 1: Audio Preprocessing**\n- Beat/onset detection (LibROSA)\n- Phoneme extraction (Rhubarb Lip Sync or mock fallback)\n- Lyrics parsing (manual or automated with Whisper)\n- JSON output for downstream processing\n\n**Phase 2: Blender Rendering**\n- 2D Grease Pencil mode (fast, stylized)\n- 3D mesh mode (planned)\n- Hybrid mode (planned)\n- Automated lip sync from phonemes\n- Beat-synchronized gestures\n- Timed lyric text objects\n\n**Phase 3: Video Export**\n- FFmpeg integration (H.264, H.265, VP9)\n- Quality presets (low, medium, high, ultra)\n- Preview mode for rapid iteration\n- Audio synchronization\n\n**Phase 4: 2D Animation System**\n- Image-to-stroke conversion\n- Grease Pencil animation\n- ~2x faster rendering than 3D\n- Stylized artistic output\n\n### Technical Highlights\n\n**Headless Rendering**\n- Tested in Docker containers with Xvfb\n- No GUI required\n- Cloud deployment ready (AWS, GCP)\n- See [CASE_STUDIES.md](CASE_STUDIES.md) for cloud setup\n\n**Performance Optimization**\n- Progressive quality configs (180p → 360p → 1080p)\n- Render time: 4 min (ultra-fast) to 50 min (production) for 30s video\n- Benchmarks included in [CASE_STUDIES.md](CASE_STUDIES.md)\n\n**Automated Lyrics**\n- Whisper integration for auto-transcription\n- Gentle forced alignment\n- Beat-based distribution\n- See [AUTOMATED_LYRICS_GUIDE.md](AUTOMATED_LYRICS_GUIDE.md)\n\n---\n\n## Configuration-Based Workflow\n\n**No code changes needed** - just swap YAML files:\n\n```yaml\n# config_ultra_fast.yaml (testing - 4 min render)\nvideo:\n  resolution: [320, 180]\n  fps: 12\n  samples: 16\n\n# config_quick_test.yaml (preview - 12 min render)\nvideo:\n  resolution: [640, 360]\n  fps: 24\n  samples: 32\n\n# config.yaml (production - 50 min render)\nvideo:\n  resolution: [1920, 1080]\n  fps: 24\n  samples: 64\n```\n\nRun with: `python main.py --config \u003cconfig_file\u003e`\n\n---\n\n## Usage Examples\n\n### Basic Pipeline\n\n```bash\n# Run complete pipeline (all 3 phases)\npython main.py --config config.yaml\n\n# Run individual phases\npython main.py --config config.yaml --phase 1  # Audio prep only\npython main.py --config config.yaml --phase 2  # Render only\npython main.py --config config.yaml --phase 3  # Export only\n\n# Validate configuration\npython main.py --config config.yaml --validate\n```\n\n### Automated Lyrics\n\n```bash\n# Instead of manual lyrics.txt, auto-generate with Whisper\npip install openai-whisper\npython auto_lyrics_whisper.py assets/song.wav --output assets/lyrics.txt\n\n# Then run pipeline as normal\npython main.py\n```\n\n### Quick Testing\n\n```bash\n# Use ultra-fast config for rapid iteration (4 min for 30s video)\npython main.py --config config_ultra_fast.yaml\n\n# Or use the quick test script\npython quick_test.py --auto-lyrics --debug\n```\n\n---\n\n## Extension Examples\n\n### Adding a New Animation Mode\n\nSee [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for complete tutorials.\n\n**Quick example** - Add particle system mode:\n\n1. Create `particle_system.py` with builder class\n2. Register in `blender_script.py` dispatcher\n3. Add `mode: \"particles\"` to config\n4. Run pipeline - no other code changes needed\n\n**Full tutorial with code samples** in DEVELOPER_GUIDE.md\n\n### Adding a New Effect\n\n**Example** - Camera shake on beats:\n\n```python\n# effects.py\nclass CameraShakeEffect:\n    def apply(self, camera):\n        for beat_frame in self.prep_data['beats']['beat_frames']:\n            # Add shake keyframes\n            camera.location = shake_position\n            camera.keyframe_insert(data_path=\"location\", frame=beat_frame)\n```\n\nAdd to config:\n```yaml\neffects:\n  camera_shake:\n    enabled: true\n    intensity: 0.2\n```\n\n**Full implementation** in DEVELOPER_GUIDE.md\n\n---\n\n## Project Structure\n\n```\nsemantic-foragecast-engine/\n├── main.py                      # Orchestrator\n├── prep_audio.py                # Phase 1: Audio analysis\n├── blender_script.py            # Phase 2: Blender automation\n├── grease_pencil.py             # 2D animation mode\n├── export_video.py              # Phase 3: FFmpeg export\n├── config.yaml                  # Production config\n├── config_ultra_fast.yaml       # Fast testing config\n├── config_360p_12fps.yaml       # Mid-quality config\n├── quick_test.py                # Automated testing script\n├── auto_lyrics_whisper.py       # Automated lyrics (Whisper)\n├── auto_lyrics_gentle.py        # Automated lyrics (Gentle)\n├── auto_lyrics_beats.py         # Beat-based lyrics\n├── assets/                      # Sample inputs\n│   ├── song.wav                 # 30s test audio\n│   ├── fox.png                  # Mascot image\n│   └── lyrics.txt               # Timed lyrics\n├── outputs/                     # Generated outputs\n│   ├── ultra_fast/              # Fast test outputs\n│   ├── test_360p/               # Mid-quality outputs\n│   └── production/              # High-quality outputs\n├── docs/                        # Documentation\n│   ├── ARCHITECTURE.md          # System design\n│   ├── DEVELOPER_GUIDE.md       # Extension tutorials\n│   ├── CASE_STUDIES.md          # Benchmarks \u0026 examples\n│   ├── TESTING_GUIDE.md         # Quality/speed configs\n│   ├── AUTOMATED_LYRICS_GUIDE.md\n│   └── POSITIONING_GUIDE.md\n└── tests/                       # Unit tests\n```\n\n---\n\n## Performance Benchmarks\n\n**30-second video render times** (tested in cloud container, CPU only):\n\n| Config | Resolution | FPS | Samples | Render Time | File Size | Use Case |\n|--------|-----------|-----|---------|-------------|-----------|----------|\n| Ultra Fast | 320x180 | 12 | 16 | **4 min** | 489 KB | Testing pipeline |\n| 360p 12fps | 640x360 | 12 | 16 | **6 min** | 806 KB | Quality check |\n| Quick Test | 640x360 | 24 | 32 | **13 min** | ~1.5 MB | Preview |\n| Production | 1920x1080 | 24 | 64 | **50 min** | ~8 MB | Final output |\n\n**Key finding**: 360p @ 12fps is the sweet spot for development (6 min, good quality)\n\nSee [CASE_STUDIES.md](CASE_STUDIES.md) for complete benchmarks and optimization strategies.\n\n---\n\n## Technical Stack\n\n**Core**:\n- Python 3.11+\n- Blender 4.0+ (Python API)\n- FFmpeg 4.4+\n\n**Audio Analysis**:\n- LibROSA 0.10.1 (beat detection, tempo)\n- Rhubarb Lip Sync (phoneme extraction)\n- Whisper (optional, auto lyrics)\n\n**Rendering**:\n- Blender EEVEE engine\n- Grease Pencil for 2D mode\n- Xvfb for headless rendering\n\n**Configuration**:\n- PyYAML 6.0.1\n- JSON for intermediate data\n\n---\n\n## Platform Support\n\n- **Development**: Windows 11, macOS, Linux\n- **Production**: Ubuntu 22.04/24.04 (tested in Docker)\n- **Cloud**: AWS EC2, GCP Compute (headless mode)\n- **Offline**: No cloud dependencies required\n\nSee [CROSS_PLATFORM_DEV_GUIDE.md](CROSS_PLATFORM_DEV_GUIDE.md) for setup instructions.\n\n---\n\n## Real-World Applications\n\n**Tested Use Cases**:\n1. **Music lyric videos** - Automated generation for indie musicians\n2. **Podcast visualization** - Animated host for audio podcasts\n3. **Educational content** - Narrated lessons with animated teacher\n4. **Brand mascot videos** - Company mascot delivering announcements\n\n**Deployment Scenarios**:\n- Local rendering (Windows/Mac development)\n- Docker containers (reproducible builds)\n- Cloud rendering (AWS/GCP for batch processing)\n- CI/CD integration (automated video generation)\n\nSee [CASE_STUDIES.md](CASE_STUDIES.md) for detailed case studies.\n\n---\n\n## Why This Project Exists\n\n**Problem**: Few production-ready examples exist for Blender automation. Most tutorials show basic concepts but not real-world architecture.\n\n**Solution**: This project demonstrates:\n- How to structure a multi-phase pipeline\n- Configuration-first design patterns\n- Headless rendering in cloud environments\n- Audio-driven procedural animation\n- Extensible plugin architecture\n\n**Target Audience**:\n- Developers learning Blender Python API\n- Pipeline engineers building automation tools\n- DevOps teams deploying headless rendering\n- Anyone needing automated video generation\n\n---\n\n## Detailed Usage\n\n### Phase 1: Audio Preparation\n\n```bash\n# Run audio prep manually\npython prep_audio.py assets/song.wav --output outputs/prep_data.json\n\n# With lyrics\npython prep_audio.py assets/song.wav --lyrics assets/lyrics.txt --output outputs/prep_data.json\n\n# With Rhubarb for real phonemes (not mock)\npython prep_audio.py assets/song.wav --rhubarb /path/to/rhubarb --output outputs/prep_data.json\n```\n\n**Output**: `prep_data.json` containing beats, phonemes, and lyrics timing\n\n### Phase 2: Blender Rendering\n\n```bash\n# Render with 2D Grease Pencil mode (fastest)\npython main.py --config config.yaml --phase 2\n\n# Enable debug visualization (colored position markers)\n# Set debug_mode: true in config.yaml, then:\npython main.py --config config.yaml --phase 2\n```\n\n**Output**: PNG frames in `outputs/*/frames/`\n\n### Phase 3: Video Export\n\n```bash\n# Encode frames to video\npython main.py --config config.yaml --phase 3\n\n# Or use export_video.py directly\npython export_video.py \\\n  --frames outputs/frames \\\n  --audio assets/song.wav \\\n  --output outputs/video.mp4 \\\n  --quality high\n```\n\n**Output**: Final MP4 video\n\n### Automated Lyrics\n\n```bash\n# Method 1: Whisper (auto-transcribe, no lyrics needed)\npip install openai-whisper\npython auto_lyrics_whisper.py assets/song.wav --output assets/lyrics.txt\n\n# Method 2: Gentle (align known lyrics to audio)\ndocker run -p 8765:8765 lowerquality/gentle\npython auto_lyrics_gentle.py --audio song.wav --lyrics text.txt --output lyrics.txt\n\n# Method 3: Beat-based (distribute lyrics on beats)\npython auto_lyrics_beats.py --prep-data prep_data.json --lyrics-text \"Your lyrics here\"\n```\n\nSee [AUTOMATED_LYRICS_GUIDE.md](AUTOMATED_LYRICS_GUIDE.md) for detailed comparison.\n\n---\n\n## Configuration Reference\n\n### Video Settings\n\n```yaml\nvideo:\n  resolution: [1920, 1080]  # Output resolution\n  fps: 24                   # Frame rate\n  render_engine: \"EEVEE\"    # EEVEE (fast) or CYCLES (quality)\n  samples: 64               # Render samples (16-256)\n  codec: \"libx264\"          # Video codec\n  quality: \"high\"           # low, medium, high, ultra\n```\n\n### Animation Settings\n\n```yaml\nanimation:\n  mode: \"2d_grease\"         # 2d_grease, 3d, or hybrid\n  enable_lipsync: true      # Phoneme-based lip sync\n  enable_gestures: true     # Beat-synced movement\n  enable_lyrics: true       # Timed lyric text\n  gesture_intensity: 0.7    # 0.0-1.0\n```\n\n### Style Settings\n\n```yaml\nstyle:\n  lighting: \"jazzy\"         # Lighting preset\n  colors:\n    primary: [0.8, 0.3, 0.9]\n    secondary: [0.3, 0.8, 0.9]\n    accent: [0.9, 0.8, 0.3]\n  background: \"solid\"       # solid or hdri\n\ngp_style:                   # 2D mode only\n  stroke_thickness: 3\n  ink_type: \"clean\"         # clean, sketchy, wobbly\n  enable_wobble: false\n  wobble_intensity: 0.5\n```\n\n### Advanced Settings\n\n```yaml\nadvanced:\n  debug_mode: false         # Show position markers\n  preview_mode: false       # Low-res preview\n  preview_scale: 0.5        # Preview resolution scale\n  threads: null             # Render threads (null = auto)\n  verbose: true             # Detailed logging\n```\n\n---\n\n## Testing\n\n### Unit Tests\n\n```bash\n# Run all tests\npython -m unittest discover tests/\n\n# Test specific phase\npython tests/test_prep_audio.py\npython tests/test_export_video.py\n```\n\n### Integration Tests\n\n```bash\n# Test complete pipeline with ultra-fast config\npython main.py --config config_ultra_fast.yaml\n\n# Automated testing script\npython quick_test.py\n```\n\n### Manual Verification\n\n```bash\n# Enable debug mode to visualize positioning\n# In config.yaml: debug_mode: true\npython main.py --config config.yaml --phase 2\n\n# Check frame 100 for colored markers\nls outputs/*/frames/frame_0100.png\n```\n\n---\n\n## Troubleshooting\n\n### Blender Not Found\n\n```bash\n# Linux: Install via apt\nsudo apt-get install blender\n\n# Mac: Install via Homebrew\nbrew install --cask blender\n\n# Windows: Download installer\n# https://www.blender.org/download/\n```\n\n### Headless Rendering Fails\n\n```bash\n# Install Xvfb virtual display\nsudo apt-get install xvfb\n\n# Run with xvfb-run\nxvfb-run -a python main.py --config config.yaml --phase 2\n```\n\n### FFmpeg Not Found\n\n```bash\n# Linux\nsudo apt-get install ffmpeg\n\n# Mac\nbrew install ffmpeg\n\n# Windows: Download from https://ffmpeg.org/\n```\n\n### Lyrics Behind Mascot\n\nCheck positioning in config - text should be at `y=-2.0, z=0.2`:\n- See [POSITIONING_GUIDE.md](POSITIONING_GUIDE.md)\n- Enable `debug_mode: true` to see position markers\n\n---\n\n## Contributing\n\n### How to Contribute\n\n1. Fork the repository\n2. Create feature branch: `git checkout -b feature/my-feature`\n3. Make changes with tests\n4. Update documentation\n5. Submit pull request\n\n### What We're Looking For\n\n- New animation modes (3D, particle systems, etc.)\n- Audio analysis improvements (melody extraction, harmony)\n- Effects (camera movements, post-processing)\n- Performance optimizations\n- Bug fixes with tests\n- Documentation improvements\n\nSee [DEVELOPER_GUIDE.md](DEVELOPER_GUIDE.md) for extension tutorials.\n\n---\n\n## Roadmap\n\n### Completed ✅\n- [x] Phase 1: Audio preprocessing\n- [x] Phase 2: Blender automation\n- [x] Phase 3: Video export\n- [x] Phase 4: 2D Grease Pencil mode\n- [x] Headless rendering support\n- [x] Automated lyrics (Whisper)\n- [x] Debug visualization\n- [x] Comprehensive documentation\n\n### Planned 🚧\n- [ ] 3D mesh animation mode\n- [ ] Hybrid mode (2D + 3D)\n- [ ] Advanced effects (fog, particles, camera shake)\n- [ ] Melody extraction and pitch-based animation\n- [ ] Multi-character support\n- [ ] Web UI for configuration\n- [ ] Real-time preview\n\n---\n\n## FAQ\n\n**Q: Can I use this for commercial projects?**\nA: Yes, MIT licensed. Attribution appreciated.\n\n**Q: Why is rendering slow?**\nA: Use `config_ultra_fast.yaml` for testing (4 min). Production 1080p takes 50 min for 30s video.\n\n**Q: Can I run this without Blender installed?**\nA: No, Phase 2 requires Blender. But you can run Phase 1 (audio prep) standalone.\n\n**Q: Does this require GPU?**\nA: No, CPU rendering works. GPU recommended for faster production renders.\n\n**Q: Can I deploy this in Docker?**\nA: Yes, see [CASE_STUDIES.md](CASE_STUDIES.md) for cloud deployment example.\n\n**Q: Is this AI-generated?**\nA: No, this is procedural animation based on audio analysis, not machine learning.\n\n---\n\n## License\n\nMIT License - See LICENSE file for details\n\n---\n\n## Acknowledgments\n\n- [LibROSA](https://librosa.org/) - Audio analysis library\n- [Rhubarb Lip Sync](https://github.com/DanielSWolf/rhubarb-lip-sync) - Phoneme extraction\n- [Blender](https://www.blender.org/) - 3D creation suite\n- [FFmpeg](https://ffmpeg.org/) - Video encoding\n- [Whisper](https://github.com/openai/whisper) - Speech recognition\n\n---\n\n## Links\n\n- **Documentation**: See `docs/` directory\n- **Issues**: [GitHub Issues](https://github.com/semanticintent/semantic-foragecast-engine/issues)\n- **Discussions**: [GitHub Discussions](https://github.com/semanticintent/semantic-foragecast-engine/discussions)\n\n---\n\n**Built with ❤️ for the Blender automation community**\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemanticintent%2Fsemantic-foragecast-engine","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fsemanticintent%2Fsemantic-foragecast-engine","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fsemanticintent%2Fsemantic-foragecast-engine/lists"}