Get Started with Smart Classroom#

Important

Use Windows PowerShell (not Command Prompt/CMD) for all steps in this guide. PowerShell scripts (.ps1 files) will not execute in CMD — they will only open as text files.

There are two ways to run Smart Classroom. Both use the same services, models and configurations.

Desktop app (recommended)

PowerShell scripts

Commands to run

.\start-desktop-app.ps1

.\setup-smart-classroom.ps1, then .\start-smart-classroom.ps1

Prerequisites and installs

Setup screen, one item at a time

One scripted pass through everything

Settings

Configuration screen

Console prompts, then editing config.yaml by hand

Services

Services screen: start, stop, restart, live logs

Separate console windows

Where the UI runs

Its own desktop window

Browser at http://localhost:5173

Whichever you pick, start by cloning the repository.

Clone the Repository#

Go to the target directory of your choice and clone the suite. If you want to clone a specific release branch, replace main with the desired tag. To learn more on partial cloning, check the Repository Cloning guide.

git clone --filter=blob:none --sparse --branch main https://github.com/open-edge-platform/education-ai-suite.git
cd education-ai-suite
git sparse-checkout set smart-classroom
cd smart-classroom

Desktop App#

The desktop app covers setup, configuration and running the services in one window.

Step 1: Launch the App#

.\start-desktop-app.ps1

The script asks for your proxy settings, installs Node.js through winget if it is missing, builds the UI and hands over. The app then supervises the Python services itself.

Optional parameters:

  • -Dev — Run the Vite dev server with hot reload

  • -NoAutoStart — Open the app without starting the backend automatically

  • -SkipNodeInstall — Fail instead of installing Node.js when it is missing

  • -Silent — Skip the proxy prompts and use the saved .proxy-config

Step 2: Work Through the Setup Screen#

Get started opens first and lists what is still missing. Follow its links, or open Setup directly, and work down the list:

Section

Covers

System and drivers

Operating system, processor, memory, free disk space, Intel GPU and NPU drivers, Windows long paths

Software and environment

Python 3.12, Node.js, FFmpeg, DL Streamer, the Python environment, and the grading conversion environment and layout detection model

Each row shows what was found and what it blocks. Rows the app can fix have a button: Install for Python, FFmpeg and DL Streamer, Create for the Python environment, Prepare for the layout detection model. Fix n items at the top runs everything outstanding in order. Progress appears in the Output pane below, and Copy diagnostics puts the whole list on the clipboard for a bug report.

Note

Creating the Python environment downloads several gigabytes, and preparing the layout detection model downloads and converts it. Both take a while on a first run.

The backend cannot start until the Python environment exists.

Step 3: Review the Settings#

Get started shows the settings most people change. The Configuration screen has the full list from config.yaml, runtime_config.yaml and .proxy-config, grouped and searchable. Saving a change while the services are running offers a restart.

Note

Speaker diarization (identifying who is speaking) is optional and requires a one-time Hugging Face access token. The Get started screen flags this when diarization is enabled without a token; set it under Configuration, or see Speaker Diarization Setup.

Step 4: Use the App#

The backend starts automatically once setup is complete, unless you passed -NoAutoStart.

Screen

What it does

Get started

Overview of what is ready, what is missing, and the settings most people change

Setup

Prerequisite checks plus the Python environment and model preparation

Configuration

Edit config.yaml, runtime_config.yaml and .proxy-config

Services

Start / stop / restart the backend and watch live logs for it and every child service

Alternative: PowerShell Scripts and the Browser UI#

Use this path for unattended installs or when you want the services in visible console windows.

Step 1: Run the Setup Script (First-Time Only)#

.\setup-smart-classroom.ps1

Note

If all prerequisites are already installed (FFmpeg, DL Streamer, Python dependencies), you can skip setup and go straight to .\start-smart-classroom.ps1.

The setup script will:

  1. [1] Check System Requirements

    • OS version, CPU, RAM, storage

    • Python and Node.js versions

  2. [2] Application Dependency Check

  3. [3] Configure Settings

    • [3.1] Feature Configuration (enable/disable individual application features)

    • [3.2] Language & ASR Configuration (provider, model, device)

    • [3.3] Upload Size Limits

    • [3.4] OCR Configuration

    • [3.5] Board OCR Configuration

    • [3.6] Grading Configuration (enable/disable Smart Grading)

Note

Speaker diarization (identifying who is speaking) is optional and requires a one-time Hugging Face access token setup if enabled — see Speaker Diarization Setup.

Step 2: Start the Services#

Use the start script for subsequent runs, or after modifying config.yaml:

.\start-smart-classroom.ps1

Optional parameters:

  • -Electron - Shortcut for .\start-desktop-app.ps1 (see Desktop App)

  • -Silent - Unattended mode for CI/Ansible (skips all prompts, auto-restarts services)

  • -NoElevate - Skip admin privilege elevation (use when already running as administrator)

  • -NoWindowsTerminal - Use Invoke-WmiMethod instead of Windows Terminal (for remote sessions/Ansible)

# Example: Automated deployment
.\start-smart-classroom.ps1 -Silent -NoElevate -NoWindowsTerminal

The startup script performs:

  • Service Detection - Checks running services

  • Restart Options - Restart, skip, or abort choices (auto in -Silent mode)

  • Proxy Configuration - Loads from .proxy-config

  • Sequential Launch - Backend -> Content Search -> Grading (if enabled) -> Frontend

  • Graceful Shutdown - Q to stop all, E to keep running (auto-exits in -Silent mode)

Step 3: Open the UI#

Once all services are running, open your browser:

Automated Setup - Troubleshooting#

If you encounter issues during automated setup, refer to the manual steps below:

Issue

Solution

PSSecurityException when running .ps1 scripts

Run Set-ExecutionPolicy -Scope Process -ExecutionPolicy Bypass in PowerShell

FFmpeg installation fails

See Manual Step 1A

DL Streamer download fails

See Manual Step 1B

Python dependencies fail

See Manual Step 1D

Content Search fails

See Manual Step 4

Frontend fails to start

See Manual Step 6

Manual Setup#

Advanced Setup Guide: Follow step-by-step instructions to set up the application.

Advanced Setup guide covers:

  • Step 1: Install Dependencies (FFmpeg, DL Streamer, Python, Content Search)

  • Step 2: Configuration (config.yaml settings, including optional Speaker Diarization Setup)

  • Step 3-6: Run Services & Access UI

  • Troubleshooting — solutions for common setup and runtime issues

  • Known Issues — current limitations and workarounds

  • Uninstall the Application — steps to cleanly remove the environment and models

Service Ports Reference#

Service

Port

Health Check

Backend

8000

http://localhost:8000/health

Content Search

9011

http://localhost:9011/api/v1/system/health (200 only when ChromaDB, file ingest and video preprocess are ready too; 503 while any is starting)

Layout Detection

9902

http://localhost:9902/health

Grading

9012

http://localhost:9012/api/v1/health

Frontend

5173

http://localhost:5173

Note

Layout Detection and Grading services only start when grading.enabled: true in config.yaml. The desktop app is its own frontend and does not use port 5173.

Learn More#