edu-shorts 1.0.0

Automatically generate short educational videos from the latest research.

Edu-Shorts Package

edu-shorts is a Python package to automatically generate educational AI-powered YouTube Shorts/Instagram Reels/TikTok videos from the latest scientific research on a user-provided topic. It gathers the latest scientific research on the topic and integrates AI for script generation, voiceover creation, and visual content sourcing to create high-quality faceless videos optimized for social media platforms. The APIs used are entirely free with daily usage limits.

Requirements

• Python 3.7+
• Two free API keys (Pexels and Groq)
• FFmpeg: This package requires FFmpeg for audio processing. MoviePy provides a lightweight installation through imageio-ffmpeg. For more robust use cases, please install it on your system
• Config file with prompts and constants
• Media assets for branding and video production

Check out the example env file, example config file and media section for details. The official GitHub repository includes a sample config file and media assets to help you get started quickly.

✨ Features

• 🤖 AI-Powered Script Generation - Uses Groq API for intelligent content creation
• 📚 Scientific Research Integration - Incorporates recent research papers via Semantic Scholar
• 🎙️ Professional Voiceover - Automated text-to-speech via Groq API
• 🎥 Stock Video Integration - Automatic visual content sourcing from Pexels
• 📱 Mobile-Optimized Output - Perfect 1080x1920 format for social media
• 🎯 Force-Aligned Subtitles - Precise subtitle timing with customizable, viral-style effects
• 🔄 Complete Automation - From topic to final video with minimal intervention

🚀 Quick Start

Installation

pip install edu-shorts

Setup

1. API Keys: Obtain free API keys from Pexels and Groq.

2. Environment Variables: Create a .env file in the root directory with the following content:

   GROQ_API_KEY=your_groq_api_key
   PEXELS_API_KEY=your_pexels_api_key
   

3. Directory Structure: Create the following directory structure in your working directory:

   your_project/
   ├── config/
   │   └── settings.yaml
   ├── media/
   │   ├── cta/
   │   ├── fonts/
   │   ├── hooks/
   │   └── music/
   ├── data/
   │   └── keywords.txt
   └── output/
   

4. Configuration File: Create a config/settings.yaml file based on the provided example to customize prompts, roles, and other settings. This file allows you to tailor the AI's behavior and video style to your brand. See the example config file and README for guidance.

   • AI prompts and roles
   • Content style and tone
   • File paths and media assets
   • Subtitle styling
   • Call-to-action settings

5. Media Assets: Prepare any brand-specific media (e.g., logos, intro/outro clips) and place them in the appropriate directories as specified in your config file. See the Media Examples section below for guidance.

6. Keyword List: Prepare a text file with a list of keywords or topics for video generation. Each line should contain a single topic. See the example keyword list. Ensure that your config file points to this keyword list. Alternatively, you can provide a single topic directly via command line arguments.

7. Verify Setup: Verify that you have properly set up the environmental variables and directory structures.

python3 -m edu-shorts --check-setup

Usage

python3 -m edu-shorts -t (optional if no keywords.txt) $KEYWORDTOPIC -o (optional default data/TIMESTAMP_Topic) $OUTPUT_DIR -n (optional default 4) $NUMCLIPSPERLINE -nd (optional if no video description needed) -cv (optional if wanting to automatically delete visuals after video creation) -ca (optional if wanting to automatically delete audio after video creation)

# Example:
python3 -m edu-shorts -t "Mental health benefits of meditation" -o output/meditation_video -n 5 -nd -cv -ca

If needing to rebuild from edited script:

python3 -m edu-shorts.merge_voiceover -o $OUTPUT_DIR
python3 -m edu-shorts.create_video_from_audio -t $KEYWORDTOPIC -o $OUTPUT_DIR -n (optional default 4) $NUMCLIPSPERLINE -d (optional if description needed)

Media Examples

• CTA: Place call-to-action media in media/cta/:
  • (Suggested: cta.mp4 and cta.wav for a built-in call-to-action video clip with audio to add to the end of your videos and cta.png if you would like to add a still image to the end).
  • Fonts: Add any custom fonts in media/fonts/ for subtitle styling.
  • Hooks: Include engaging video hooks in media/hooks/ to capture viewer attention.
  • Music: Add background music tracks in media/music/ to enhance video engagement.

Package Overview

The main entry point is the create-edu-short() function in __main__.py, which orchestrates the entire video creation pipeline:

1. Topic Selection: Automatically selects unused topics from keyword lists
2. Research: Fetches recent scientific papers related to the topic
3. Script Generation: Uses AI to create engaging video scripts
4. Audio Creation: Converts scripts to high-quality voiceover audio
5. Visual Generation: Sources and downloads relevant stock videos
6. Subtitle Creation: Generates force-aligned, styled subtitles
7. Video Assembly: Combines all elements into a final video
8. Description Generation: Creates video descriptions and metadata

Dependencies

The package relies on several external services and libraries:

• Groq API for AI-powered content generation
• Pexels API for stock video content
• Semantic Scholar API for research papers
• MoviePy for video processing
• ForceAlign for subtitle timing
• Various audio processing libraries

Configuration

All configuration is managed through YAML files, including:

• AI prompts and roles
• API settings
• Video styling parameters
• Brand tone and messaging guidelines

Main Function

1. main.py: Contains the main create-edu-short() function and orchestrates the entire video creation process from a keyword list or given topic.

Core Files for Fine-Tuned Video Creation

2. build_video.py: Handles the final video assembly and rendering when all required components are already in the output directory.
3. clean_output.py: Cleans up intermediate files and directories after video creation.
4. create_video_from_audio.py: Creates videos starting from audio files.
5. create_video_from_script.py: Creates videos starting from text scripts.
6. create_video_from_srt.py: Creates videos using SRT subtitle files as input.
7. get_hook.py: Generates engaging hooks for video content.
8. merge_voiceover.py: Combines multiple audio segments into a single voiceover track.

API Module (api/)

Handles external API integrations:

• groq.py: Interface for Groq AI API calls for script generation, refinement, and content creation
• pexels.py: Integration with Pexels API for stock video and image retrieval
• semanticscholar.py: Interface with Semantic Scholar API for fetching recent scientific papers and research

Audio Module (audio/)

• voiceover.py: Handles text-to-speech conversion, audio file creation, and voiceover processing

Configuration Module (config/)

• config_loader.py: Loads and validates configuration settings from YAML files, manages prompts and AI roles

Script Module (script/)

• script_generator.py: Generates video scripts using AI, including content prompts, script refinement, and critique functionality

Subtitles Module (subtitles/)

• srt_utils.py: Utilities for parsing, creating, and manipulating SRT subtitle files
• subtitle_styles.py: Defines styling options for viral-style subtitles with colors and effects
• subtitles.py: Main subtitle processing, including force alignment and word-level timing

Utils Module (utils/)

• file_ops.py: File operations including directory creation, file management, and path utilities
• logging.py: Logging functionality for tracking script generation and debugging
• text_processing.py: Text manipulation utilities including number-to-word conversion and text cleaning

Video Module (video/)

• generate_visuals.py: Handles stock video search, download, and visual content generation
• video_builder.py: Core video assembly functionality, combining audio, visuals, and subtitles
• visual_cues.py: Generates visual cues and manages video segment timing

Key Features

Automated Workflow

• Complete automation from topic selection to final video output
• Integration with multiple AI services for content generation
• Automated visual content sourcing from stock video APIs

Scientific Content Integration

• Fetches recent scientific papers related to health and wellness topics
• Incorporates research findings into video scripts
• Maintains scientific accuracy while creating engaging content

Professional Video Production

• Force-aligned subtitles for precise timing
• Viral-style subtitle effects with custom styling
• Mobile-optimized video format (1080x1920)
• Professional voiceover generation

Modular Architecture

• Clean separation of concerns across modules
• Easy to extend and maintain
• Comprehensive error handling and logging

License

This project is licensed under the GNU General Public License v3.0 (GPLv3).

• Individuals and creators are free to use this tool to generate and monetize their own videos without restriction.
• If you wish to integrate this project into a commercial product or SaaS platform without open-sourcing your code, a separate commercial license is available.

For commercial licensing inquiries, please contact: [e-mail].