Automated tool to schedule YouTube live broadcasts for recurring services and special events.

• Environment-based configuration through .env file
• Support for multiple services (A-H) with configurable stream keys
• Automatic scheduling calculations for recurring services
• Date range mode for scheduling multiple services across custom periods
• Dry run mode for preview without creating broadcasts
• Detailed logging and error handling

• Python 3.9 or higher
• Google Cloud Platform account
• YouTube channel with live streaming enabled
• Access to YouTube Data API v3

Follow these steps to install the tool from scratch. The commands automatically adapt to wherever you clone the repository.

Visit brew.sh for installation instructions.

brew install python

Verify installation:

python3 --version

# Clone the repository to your preferred location
git clone <repository-url>
cd yt-schedule

# Create virtual environment
python3 -m venv venv

# Install dependencies
venv/bin/pip install -r requirements.txt
venv/bin/pip install -e .

Add an alias to your shell configuration to run the tool from anywhere. Run these commands from within the yt-schedule directory:

For zsh (default on macOS):

echo "alias yt-schedule='cd $(pwd) && venv/bin/yt-schedule'" >> ~/.zshrc
source ~/.zshrc

For bash:

echo "alias yt-schedule='cd $(pwd) && venv/bin/yt-schedule'" >> ~/.bashrc
source ~/.bashrc

How it works: The $(pwd) command captures your current directory path when you run it. This means:

• If you're in /Users/alice/code/yt-schedule, the alias will use that path
• If you're in /opt/tools/yt-schedule, the alias will use that path
• Works with any directory structure, no manual editing needed

From any directory, test that the alias works:

yt-schedule --help

You can now run yt-schedule from anywhere!

What the alias does: When you run yt-schedule, it:

1. Changes to your project directory (wherever you cloned it)
2. Runs the tool from the virtual environment
3. Passes along any arguments you provide

This ensures the tool always finds its configuration files, regardless of where you run the command from.

If you prefer to run the tool directly without the global alias:

# Navigate to wherever you cloned the repository
cd /path/to/yt-schedule

# Install dependencies
pip3 install -r requirements.txt

# Run the tool
python3 main.py --help

Note: With this approach, use python3 main.py instead of yt-schedule for all commands (e.g., python3 main.py -w 4). You must run commands from the project directory.

If you want to activate the virtual environment in your current shell for development:

# Navigate to wherever you cloned the repository
cd /path/to/yt-schedule

# Create and activate virtual environment
python3 -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt
pip install -e .

# Test it works
yt-schedule --help

Note: You'll need to run source venv/bin/activate each time you open a new terminal session. While the venv is activated, you can run yt-schedule from any directory, but the tool still expects its configuration files (.env, OAuth2.json) to be in the current working directory when you run it.

If you've installed the tool in a different location or way, you can still create a global alias. From the project directory, run:

# Detect your shell and add the alias
if [ -n "$ZSH_VERSION" ]; then
  echo "alias yt-schedule='cd $(pwd) && venv/bin/yt-schedule'" >> ~/.zshrc
  source ~/.zshrc
elif [ -n "$BASH_VERSION" ]; then
  echo "alias yt-schedule='cd $(pwd) && venv/bin/yt-schedule'" >> ~/.bashrc
  source ~/.bashrc
else
  echo "Unsupported shell. Please add the alias manually to your shell config."
fi

Or for direct execution without venv:

# Detect your shell and add the alias for direct execution
if [ -n "$ZSH_VERSION" ]; then
  echo "alias yt-schedule='cd $(pwd) && python3 main.py'" >> ~/.zshrc
  source ~/.zshrc
elif [ -n "$BASH_VERSION" ]; then
  echo "alias yt-schedule='cd $(pwd) && python3 main.py'" >> ~/.bashrc
  source ~/.bashrc
else
  echo "Unsupported shell. Please add the alias manually to your shell config."
fi

1. Navigate to Google Cloud Console
2. Create a new project or select an existing project
3. Enable the YouTube Data API v3
4. Create OAuth 2.0 credentials (Desktop app type)
5. Download the credentials JSON file

Copy the example file and add your credentials:

cp OAuth2.json.example OAuth2.json

Edit OAuth2.json with your actual OAuth 2.0 credentials from Google Cloud Console.

Security Note: OAuth2.json and token.pickle are included in .gitignore and must never be committed to version control.

The .env file will be automatically created from env.example on first run. Alternatively, you can create it manually:

cp env.example .env

Edit .env with the following required settings:

Required Settings

• CHANNEL_ID: Your YouTube channel ID
• PLAYLIST_ID: Playlist ID where broadcasts will be added
• CAMPUS_NAME: Campus identifier for stream titles (e.g., "Fishers")
• ENABLED_SERVICES: Comma-separated list of services to schedule (e.g., "A,B,C,D,E,F")

Service Configuration

Configure each service (A-H) with the following variables:

• SERVICE_X_NAME: Display name (e.g., "Saturday 4:00pm Service")
• SERVICE_X_DAY: Day of week (Monday-Sunday)
• SERVICE_X_TIME: Time in 24-hour format (e.g., "16:00")
• SERVICE_X_DESCRIPTION: Optional broadcast description

Optional Settings

• TIMEZONE: Timezone for service times (default: America/Indianapolis)
• PRIVACY_STATUS: Broadcast privacy: unlisted, private, or public (default: unlisted)
• AUTO_START: Automatically start broadcast at scheduled time: true or false (default: true)
• AUTO_STOP: Automatically stop broadcast when stream ends: true or false (default: true)
• ENABLE_DVR: Enable DVR functionality for viewers: true or false (default: true)
• ENABLE_360: Enable 360° video mode: true or false (default: false)
• DRY_RUN: Enable preview mode: true or false (default: false)

The tool automatically detects stream keys based on the naming pattern:

{CAMPUS_NAME} Stream {Letter}

Example for CAMPUS_NAME=Fishers:

• Fishers Stream A → Service A
• Fishers Stream B → Service B

Configure your stream keys in YouTube Studio to match this naming pattern.

On first run, the tool will open a browser window for OAuth authentication:

1. Log in with your Google account
2. Grant the requested permissions
3. The tool will save credentials to token.pickle

Subsequent runs will use the saved credentials automatically. Credentials refresh automatically when they expire.

Note: If you used the Direct Execution method, replace yt-schedule with python3 main.py in all commands below.

Schedule the next occurrence of each enabled service:

yt-schedule

This creates broadcasts for the next Saturday, Sunday, or Wednesday (depending on service configuration) and adds them to the specified playlist.

Schedule multiple weeks of services using the -w or --weeks flag:

yt-schedule -w 4

This schedules all enabled services for the next 4 weeks from today.

Examples:

• yt-schedule -w 1 - Schedule 1 week
• yt-schedule -w 12 - Schedule 3 months (12 weeks)
• yt-schedule -w 52 - Schedule a full year

Preview scheduled broadcasts without creating them:

yt-schedule --dry-run

Or configure in .env:

DRY_RUN=true

Remove all upcoming/scheduled broadcasts:

yt-schedule --remove

Or use the shorthand:

yt-schedule -rm

Preview what would be removed without deleting:

yt-schedule --remove --dry-run

This is useful for:

• Clearing out old scheduled broadcasts before rescheduling
• Removing broadcasts that need to be rescheduled
• Cleaning up test broadcasts

Configure .env:

ENABLED_SERVICES=A,B,C,D,E

Run the scheduler:

yt-schedule

Configure .env:

ENABLED_SERVICES=A,B,C,D,E,F

Schedule 4 weeks of services:

yt-schedule -w 4

Preview the next week of services:

yt-schedule -w 1 --dry-run

Default service configurations (all times and names are customizable):

• Service A: Saturday 4:00pm Service
• Service B: Saturday 5:30pm Service
• Service C: Sunday 8:00am Service
• Service D: Sunday 9:30am Service
• Service E: Sunday 11:15am Service
• Service F: Wednesday 7:00pm Service
• Service G: Available for additional services (requires schedule configuration)
• Service H: Available for additional services (requires schedule configuration)

Note: All services must have a schedule configured (DAY and TIME). To use a service, set the appropriate environment variables in .env.

The tool needs to run from the project directory where .env and OAuth2.json are located. This is why the alias includes cd $(pwd).

If you get "command not found":

• Verify the alias was added: alias | grep yt-schedule
• Reload your shell config: source ~/.zshrc (or ~/.bashrc)
• Check the path in the alias points to the correct location

If you get "OAuth2.json not found" or ".env not found":

• Make sure you're using the alias (which changes to the project directory first)
• If running manually, ensure you're in the project directory: cd /path/to/yt-schedule
• Verify the files exist: ls -la .env OAuth2.json

• Verify OAuth2.json exists and contains valid credentials
• Delete token.pickle and re-authenticate if credentials are corrupted
• Ensure the YouTube Data API v3 is enabled in Google Cloud Console

• Verify stream keys are configured in YouTube Studio
• Check stream key naming matches the pattern: {CAMPUS_NAME} Stream {Letter}
• Ensure CAMPUS_NAME in .env matches your stream key naming

• Verify TIMEZONE setting matches your location
• Check service time configuration in .env uses 24-hour format
• Confirm SERVICE_X_TIME values are in HH:MM format (ie: 4pm == 16:00)

• Verify all required environment variables are set in .env