Vizbee Omni Framework for Roku

A comprehensive, modular framework for building feature-rich Roku applications with content management, video playback, casting capabilities, and more.

📖 Overview

The Vizbee Omni Framework is a production-ready, modular SceneGraph framework that accelerates Roku app development. It provides pre-built components for common TV app features, allowing developers to focus on building unique experiences rather than reinventing core functionality.

Key Features

• 🎬 Video Player - Advanced player with Google IMA ads integration and Mux analytics
• 📺 CMS Integration - Flexible content management system adapter with caching
• 🔄 Vizbee Continuity - Cross-device casting and synchronization
• ⚙️ Configuration Management - Environment-based configuration system
• 🌐 Network Layer - Robust HTTP client with error handling
• 🎨 UI Components - Pre-built SceneGraph components and layouts
• 📊 Scene Coordination - Navigation and lifecycle management
• 🛠️ Developer Tools - Logging utilities, type guards, and helpers

📦 Installation

Install via npm

npm install vizbee-omni-framework-roku

Install via yarn

yarn add vizbee-omni-framework-roku

🚀 Quick Start

1. Install the Package

Add the framework to your Roku project:

npm install vizbee-omni-framework-roku

2. Copy Framework Files

The framework files need to be copied into your app's source during the build process. Add a script to your package.json:

{
  "scripts": {
    "copy:omni": "node scripts/copy-omni-framework.js",
    "prebuild": "npm run copy:omni",
    "build": "bsc"
  }
}

Create scripts/copy-omni-framework.js:

#!/usr/bin/env node

const fs = require("fs-extra");
const path = require("path");
require("dotenv").config();

// Configuration
const config = {
  sourceDir: "node_modules/vizbee-omni-framework-roku/",
  targetDir: "components/omni",
  exclude: [
    "docs",
    "README.md",
    "package.json",
    "package-lock.json",
    "bsconfig.json",
  ],
};

// Colors for console output
const colors = {
  reset: "\x1b[0m",
  green: "\x1b[32m",
  yellow: "\x1b[33m",
  blue: "\x1b[34m",
  red: "\x1b[31m",
};

function log(message, color = colors.reset) {
  console.log(`${color}${message}${colors.reset}`);
}

function copyFrameworkFiles() {
  log("\n📦 Copying omni framework files to the app...", colors.blue);

  // config.frameworkDirs.forEach(dir => {
  const sourcePath = path.join(process.cwd(), config.sourceDir);
  const targetPath = path.join(process.cwd(), config.targetDir);

  if (fs.existsSync(sourcePath)) {
    try {
      // Create target directory if it doesn't exist
      fs.ensureDirSync(targetPath);

      // Copy files
      fs.copySync(sourcePath, targetPath, {
        overwrite: true,
        filter: (src) => {
          // Skip excluded directories
          return !config.exclude.some((excluded) => src.includes(excluded));
        },
      });

      log(`  ✓ Copied to ${config.targetDir}`, colors.green);
    } catch (error) {
      log(
        `  ✗ Error copying to ${config.targetDir}: ${error.message}`,
        colors.red
      );
    }
  } else {
    log(`  ⊘ Skipped ${config.targetDir} (not found)`, colors.yellow);
  }
  // });
}

function clean() {
  log("\n🧹 Cleaning omni framework files...", colors.blue);

  try {
    const buildPath = path.join(process.cwd(), config.targetDir);
    if (fs.existsSync(buildPath)) {
      fs.removeSync(buildPath);
      log("  ✓ Cleaned omni framework files", colors.green);
    }
  } catch (error) {
    log(`  ✗ Clean error: ${error.message}`, colors.red);
  }
}

// Main execution
function main() {
  clean();
  copyFrameworkFiles();
}

main();

🏗️ Architecture

For a deeper dive into the framework's design and capabilities, see the official Omni Framework Documentation.

Core Modules

| Module | Location | Purpose | | ---------------------- | --------------------------------------------- | --------------------------------------------- | | VizbeeOmni | components/VizbeeOmni.xml | Main framework entry point and initialization | | OmniSceneManager | components/OmniSceneManager.xml | Scene navigation and lifecycle management | | OmniCMSManager | components/cms/OmniCMSManager.xml | Content management and data fetching | | OmniConfigManager | components/config/OmniConfigManager.xml | Application configuration management | | ContinuityManager | components/continuity/ContinuityManager.xml | Vizbee casting integration | | OmniPlayerManager | components/player/OmniPlayerManager.xml | Video playback orchestration | | OmniNetworkManager | components/network/OmniNetworkManager.xml | HTTP requests and API communication | | OmniPlayer | components/player/OmniPlayer.xml | Advanced video player with ads |

🛠️ Development

Prerequisites

• Node.js v14+
• BrighterScript compiler
• Roku device in Developer Mode

Local Development

When actively developing the framework alongside an app, you can link the local framework instead of using the published npm package.

Update your app's package.json to reference the local framework folder:

{
  "dependencies": {
    "vizbee-omni-framework-roku": "file:../../packages/omni"
  }
}

Then install dependencies:

npm install

This creates a symlink to your local framework, allowing you to make changes and see them immediately in your app during development.

Testing

Test the framework in the context of a real app by:

1. Creating a test app in ../../apps/test-app
2. Using the Local Development setup to link the framework
3. Building and deploying to a Roku device

📤 Publishing to npm

Prerequisites

1. npm account with publishing rights to @vizbee scope
2. Proper authentication (npm login)

Version Management

Follow Semantic Versioning:

• MAJOR version: Breaking changes
• MINOR version: New features (backward compatible)
• PATCH version: Bug fixes

Publishing Steps

1. Update Version

# For a patch release (1.0.0 -> 1.0.1)
npm version patch

# For a minor release (1.0.0 -> 1.1.0)
npm version minor

# For a major release (1.0.0 -> 2.0.0)
npm version major

This will:

• Update version in package.json
• Create a git commit with the new version
• Create a git tag

2. Build the Package

Ensure all files are compiled and ready:

# Run any build steps if needed
npm run build  # if you have a build script

# Verify package contents
npm pack --dry-run

3. Publish to npm

# Publish to npm registry
npm publish --access public

# For scoped packages (vizbee-omni-framework-roku)
npm publish --access public

4. Push to Git

# Push the version commit and tag
git push origin develop
git push origin --tags

Publishing Checklist

• [ ] All tests pass
• [ ] CHANGELOG.md updated with changes
• [ ] README.md is up to date
• [ ] Version number follows semver
• [ ] Package builds successfully
• [ ] No sensitive data in published files
• [ ] .npmignore or package.json files array is correct
• [ ] Published and verified on npmjs.com

Verify Publication

After publishing, verify the package:

# View package info
npm info vizbee-omni-framework-roku

# Install in a test project
npm install vizbee-omni-framework-roku@latest

# Check unpacked size
npm info vizbee-omni-framework-roku dist.unpackedSize

Package Configuration

Ensure package.json is properly configured:

{
  "name": "vizbee-omni-framework-roku",
  "version": "1.0.0",
  "description": "Roku Omni Framework",
  "main": "index.json",
  "files": ["components", "source", "images", "README.md", "LICENSE.md"],
  "repository": {
    "type": "git",
    "url": "git+https://github.com/ClaspTV/vizbee-omni-framework-roku.git",
    "directory": "packages/omni"
  },
  "keywords": [
    "roku",
    "scenegraph",
    "framework",
    "video",
    "streaming",
    "vizbee",
    "tv",
    "brightscript"
  ],
  "author": "Vizbee",
  "license": "ISC",
  "publishConfig": {
    "access": "public"
  }
}

Automated Publishing (CI/CD)

For automated publishing, add to your GitHub Actions workflow:

name: Publish Package

on:
  push:
    tags:
      - "v*"

jobs:
  publish:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v3
      - uses: actions/setup-node@v3
        with:
          node-version: "18"
          registry-url: "https://registry.npmjs.org"
      - run: npm ci
      - run: npm publish --access public
        env:
          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}

Additional Resources

• Roku Developer Documentation
• BrighterScript Documentation
• Vizbee Developer Portal
• Google IMA SDK for Roku

📄 License

See LICENSE.md for complete terms.

💬 Support

For issues, questions, or support:

• Open an issue on GitHub
• Contact: [email protected]