Contributing to CastConductor

Thank you for your interest in contributing to CastConductor! This guide covers how to develop custom theme packs for the CastConductor platform.

Theme Pack Overview

CastConductor theme packs allow you to create and distribute custom visual styles for Roku channels. Theme packs can include:

• Color schemes - Primary, secondary, background, surface, and text colors
• Typography settings - Font sizes and styles for headings and body text
• Background images - Full-screen or container-specific backgrounds
• Overlay graphics - PNG overlays with transparency
• Container styling - Per-container preset overrides
• Widget configuration - Clock, weather, and other widget defaults

Licensing & Monetization

You keep 100% of your sales. CastConductor does not take any revenue share from theme pack sales.

• Free themes: Share with the community at no cost
• Paid themes: Link to your own store (Gumroad, Lemonsqueezy, your website, etc.)
• Theme Directory: Submit your theme to themes.castconductor.com for discovery (free listing)

Getting Started

Prerequisites

• Familiarity with JSON
• Image editing software (Photoshop, Figma, GIMP, etc.)
• Understanding of Roku's 1280×720 coordinate space

Quick Start

1. Download the Theme Pack Starter Template
2. Edit theme.json with your theme configuration
3. Add your background images and overlays to the assets/ folder
4. Create a preview thumbnail (400×225 recommended)
5. Zip the folder and import into CastConductor

Theme Pack Structure

my-theme-pack/
├── theme.json              # Theme configuration (required)
├── README.md               # Documentation for users
├── preview/
│   ├── thumbnail.png       # Directory thumbnail (400×225)
│   └── screenshot-1.png    # Full-size screenshots
├── assets/
│   ├── backgrounds/        # Background images (1280×720)
│   │   ├── full-screen.jpg
│   │   └── lower-third.png
│   └── overlays/           # Overlay graphics (PNG with alpha)
│       ├── frame-gold.png
│       └── gradient-bottom.png
└── LICENSE                 # Your license terms

theme.json Specification

The theme.json file is the heart of your theme pack. Here's a complete example:

{
  "name": "Midnight Broadcast",
  "version": "1.0.0",
  "author": {
    "name": "Your Name",
    "email": "[email protected]",
    "url": "https://gumroad.com/yourstore"
  },
  "description": "A sleek dark theme for professional broadcasters",
  "license": "proprietary",
  "preview": {
    "thumbnail": "preview/thumbnail.png",
    "screenshots": [
      "preview/screenshot-1.png",
      "preview/screenshot-2.png"
    ]
  },
  "colors": {
    "primary": "#6200EE",
    "secondary": "#03DAC6",
    "background": "#0D0D0D",
    "surface": "#1A1A1A",
    "textPrimary": "#FFFFFF",
    "textSecondary": "#A0A0A0",
    "success": "#00C853",
    "warning": "#FFD600",
    "error": "#FF5252"
  },
  "typography": {
    "headingFont": "system",
    "bodyFont": "system",
    "headingSizes": {
      "h1": 48,
      "h2": 36,
      "h3": 28,
      "h4": 24
    },
    "bodySizes": {
      "large": 24,
      "medium": 18,
      "small": 14
    }
  },
  "containers": {
    "full_screen": {
      "background": "assets/backgrounds/full-screen.jpg"
    },
    "lower_third": {
      "background": "assets/backgrounds/lower-third.png",
      "overlay": "assets/overlays/gradient-bottom.png",
      "padding": { "top": 20, "right": 40, "bottom": 20, "left": 40 }
    }
  },
  "widgets": {
    "clock": {
      "format": "12h",
      "showSeconds": false,
      "showDate": true
    }
  },
  "roku": {
    "focusColor": "#6200EE",
    "menuStyle": "overlay",
    "transitionDuration": 300
  }
}

Required Fields

Optional Fields

Container Presets Reference

CastConductor's authoring space is 1280×720 pixels (standard 720p HD). All container presets use this coordinate system.

Full-Size Containers

Thirds (Horizontal)

Halves

Quarters

Horizontal Quarters (Full-Width Strips)

Featured + Grid Layout

A hero image with 4 grid items below:

Container Keys for theme.json

Use these keys in the containers object:

{
  "containers": {
    "full_screen": { ... },
    "upper_third": { ... },
    "center_third": { ... },
    "lower_third": { ... },
    "left_half": { ... },
    "right_half": { ... },
    "horizontal_upper_half": { ... },
    "horizontal_lower_half": { ... },
    "upper_left_quarter": { ... },
    "upper_right_quarter": { ... },
    "lower_left_quarter": { ... },
    "lower_right_quarter": { ... },
    "horizontal_1st_quarter": { ... },
    "horizontal_2nd_quarter": { ... },
    "horizontal_3rd_quarter": { ... },
    "horizontal_4th_quarter": { ... },
    "featured_grid_hero": { ... },
    "featured_grid_item_1": { ... },
    "featured_grid_item_2": { ... },
    "featured_grid_item_3": { ... },
    "featured_grid_item_4": { ... }
  }
}

Font Limitations

Available Fonts

Custom Fonts via Toaster

CastConductor supports custom fonts bundled at build time through the Toaster:

1. Upload your font - In CastConductor Settings → Roku App, upload TTF/OTF font files before generating your app
2. Fonts are compiled into the Roku package - The Toaster bundles your fonts during the "🚀 Launch Toaster" build process
3. Reference in theme.json - Use the font filename (without extension) in your typography settings

Alternatives

• Use images - For logos and display text, use PNG images instead of text layers
• Stick to system fonts - Design your theme around Roku's clean system typography

Theme Inheritance

Themes can extend a parent theme using the extends field:

{
  "name": "Midnight Blue",
  "version": "1.0.0",
  "extends": "midnight-broadcast",
  "colors": {
    "primary": "#1E88E5"
  }
}

This inherits all settings from midnight-broadcast and only overrides the primary color.

Inheritance Rules

• Child themes only need to specify overrides
• Nested objects are merged (not replaced entirely)
• Assets paths are relative to the child theme
• Use "extends": "default" to inherit from CastConductor's base theme

Asset Guidelines

Background Images

Overlay Graphics

• Use PNG format with alpha transparency
• Keep file sizes small for fast Roku loading
• Test overlays on both light and dark content

Color Values

All colors use hex format with optional alpha:

• 6-digit: #RRGGBB (e.g., #6200EE)
• 8-digit: #RRGGBBAA (e.g., #6200EE80 for 50% opacity)

Testing Your Theme

1. Import into CastConductor - Use the Theme Pack Import feature in plugin settings
2. Apply to a Scene - Select your theme in the Scene settings
3. Preview in Canvas - Check the Content Block Canvas rendering
4. Test on Roku - Sideload the app to verify device rendering

Versioning & Updates

Version Numbering

Use semantic versioning: MAJOR.MINOR.PATCH

• MAJOR: Breaking changes (layout restructure)
• MINOR: New features (additional backgrounds)
• PATCH: Bug fixes (color adjustments)

Updating Themes

Currently, users must manually re-import updated theme packs. Future updates will include:

• Version checking with update notifications
• One-click updates from the theme directory

Theme Pack Starter Template

Download the starter template to begin:

theme-pack-starter/
├── theme.json              # Pre-filled with defaults
├── README.md               # Documentation template
├── preview/
│   └── thumbnail.png       # Placeholder image
└── assets/
    ├── backgrounds/
    │   └── .gitkeep
    └── overlays/
        └── .gitkeep

Download Starter Template

Frequently Asked Questions

Can theme packs style token text layers?

Yes! Token layers (like {{track.title}} or {{weather.temperature}}) are styled exactly like regular text layers. Your theme's typography settings, colors, and font sizes apply to both static text and dynamic token content.

Are there layer count limitations?

No hard limit in CastConductor, but Roku has practical constraints:

• Recommended: Up to 20-30 layers per content block
• Performance: More layers = more texture memory usage
• Best practice: Combine similar elements, use efficient layer structures

Can I use custom containers beyond the presets?

Absolutely! The presets are starting points. You can define any geometry within the 1280×720 authoring space. Just ensure your dimensions are whole numbers and fit within the canvas bounds.

Publishing to Theme Directory

To list your theme on themes.castconductor.com:

1. Prepare your package - Ensure all assets are included
2. Create preview assets - Thumbnail (400×225) + 2-3 screenshots
3. Submit for review - Email [email protected] with:
   • Your theme pack (.zip)
   • Pricing (free or link to your store)
   • Brief description for the directory

Review Criteria

• ✅ Valid theme.json with all required fields
• ✅ Assets are appropriately sized
• ✅ No copyrighted content without proper licensing
• ✅ Renders correctly on Roku devices

Stay Updated

• Watch our Changelog for theme pack SDK announcements
• Join the Community Forum for discussions

Questions?

For theme development questions, reach out to: [email protected]