TEN Framework Quick Start Guide

TEN Framework Quick Start Guide

🎯 Goal: Set up your development environment and run your first TEN app in 5 minutes

System Requirements

Supported Operating Systems:

  • Linux (x64)
  • Linux (arm64)
  • macOS Intel (x64)
  • macOS Apple Silicon (arm64)

Required Software:

  • Python 3.10
  • Go 1.20+
  • Node.js / npm (for managing JavaScript dependencies)

Step 1: Check Your Environment

Before you begin, make sure the following software is installed on your system:

Python 3.10

python3 --version
# Should display: Python 3.10.x

💡 Recommendation: It's recommended to use pyenv or venv to create a Python 3.10 virtual environment to avoid conflicts with your system Python version:

# Create virtual environment using venv (example)
python3.10 -m venv ~/ten-venv
source ~/ten-venv/bin/activate

# Or use pyenv to manage multiple Python versions (example)
pyenv install 3.10.14
pyenv local 3.10.14

Go 1.20+

go version
# Should display: go version go1.20 or higher

Node.js / npm

node --version
npm --version
# Ensure node and npm commands are available

💡 Tip: If any of the above is missing, please install the required version before continuing.

Step 2: Install TEN Manager (tman)

TEN Manager (tman) is the command-line tool for TEN Framework, used to create projects, manage dependencies, and run applications.

One-line Installation:

curl -fsSL https://raw.githubusercontent.com/TEN-framework/ten-framework/main/tools/tman/install_tman.sh | bash

Or, if you've already cloned the repository:

cd ten-framework
bash tools/tman/install_tman.sh

Verify Installation:

tman --version

💡 Tip: If you see tman: command not found, make sure /usr/local/bin is in your PATH:

echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.bashrc  # Linux
echo 'export PATH="/usr/local/bin:$PATH"' >> ~/.zshrc   # macOS
source ~/.bashrc  # or source ~/.zshrc

Step 3: Create and Run the Demo App

Create App

# Create a new transcriber_demo app
tman create app transcriber_demo --template transcriber_demo
cd transcriber_demo

Install Dependencies

# Install TEN package dependencies
tman install

# Install Python and npm package dependencies
tman run install_deps

⏱️ Estimated Time: 1-2 minutes

Build the App

tman run build

⏱️ Estimated Time: 30 seconds

Configure Environment Variables

Before running the app, you need to configure the ASR (Automatic Speech Recognition) service credentials. The current example uses Azure ASR extension. You need to fill in the configuration in the transcriber_demo/.env file:

# Create .env file
cat > .env << EOF
# Azure Speech Service Configuration
AZURE_STT_KEY=your_azure_speech_api_key
AZURE_STT_REGION=your_azure_region      # e.g., eastus
AZURE_STT_LANGUAGE=en-US                # Set according to your audio language or real-time recording language, e.g., zh-CN, ja-JP, ko-KR, etc.
EOF

💡 Tip: If you want to use other ASR extensions (such as OpenAI Whisper, Google Speech, etc.), you can download and replace them from the cloud store. Similarly, configure the corresponding API keys and environment variables in the .env file.

Run the App

tman run start

If everything is working correctly, you should see output similar to:

[web_audio_control_go] Web server started on port 8080
[audio_file_player_python] AudioFilePlayerExtension on_start

Experience the Demo

Open your browser and visit:

http://localhost:8080

You should see the Transcriber Demo web interface. Try:

  • Click the microphone button for real-time voice transcription
  • Upload an audio file for transcription
  • View real-time transcription and subtitle results

Congratulations! 🎉

You've successfully run your first TEN application!

Understanding the App Architecture

This transcriber_demo app showcases TEN Framework's multi-language extension capabilities, consisting of:

  • Go - WebSocket server extension (web_audio_control_go)
  • Python - ASR speech recognition extension (azure_asr_python)
  • TypeScript - VTT subtitle generation and audio recording extension (vtt_nodejs)

🎯 You can now run extensions in multiple languages!

Next Steps

Now you can:

  1. Explore and download more extensions from the cloud store, design and orchestrate your app

    tman designer  # Launch TMAN Designer to explore extensions, download them, and design your app

  2. Choose a language and develop your own extension

Advanced: Developing and Building C++ Extensions

If you want to develop and use C++ extensions, you'll need to install the TEN build toolchain (tgn). Here's the complete process:

Install tgn Build Tool

tgn is TEN Framework's C/C++ build system, based on Google's GN.

Option 1: One-line Installation (Recommended)

curl -fsSL https://raw.githubusercontent.com/TEN-framework/ten-framework/main/tools/tgn/install_tgn.sh | bash

Option 2: Install from Cloned Repository

# If you've already cloned the TEN Framework repository
cd ten-framework
bash tools/tgn/install_tgn.sh

After installation, ensure tgn is added to PATH:

# Temporarily add to current session
export PATH="/usr/local/ten_gn:$PATH"

# Or permanently add to shell configuration (recommended)
echo 'export PATH="/usr/local/ten_gn:$PATH"' >> ~/.bashrc  # Linux
echo 'export PATH="/usr/local/ten_gn:$PATH"' >> ~/.zshrc   # macOS
source ~/.bashrc  # or source ~/.zshrc

Verify installation:

tgn --help

Install C++ Extension

Using WebRTC VAD (Voice Activity Detection) extension as an example, install a C++ extension from the cloud store:

cd transcriber_demo
tman install extension webrtc_vad_cpp

💡 Note: webrtc_vad_cpp is a voice activity detection extension implemented in C++. It can filter out non-speech segments in real-time speech recognition scenarios.

Compile C++ Extension

After installing the C++ extension, rebuild the app to compile the C++ code into a dynamic library:

tman run build

⏱️ Expected Time: First-time compilation of C++ extensions may take 1-3 minutes, depending on your machine's performance.

Run App with VAD Functionality

tman run start_with_vad

If everything works correctly, you should see:

[web_audio_control_go] Web server started on port 8080
[vad] WebRTC VAD initialized with mode 2
[audio_file_player_python] AudioFilePlayerExtension on_start

Now open your browser at http://localhost:8080 and navigate to the microphone real-time transcription page. You'll see the silence state changes after VAD processing. When the silence state is true, it indicates there is no speech in the current audio.

C++ Development Environment Requirements

Developing and compiling C++ extensions requires installing a C++ compiler (gcc or clang):

Linux:

# Ubuntu/Debian
sudo apt-get install gcc g++

# Or use clang
sudo apt-get install clang

macOS:

# Install Xcode Command Line Tools (includes clang)
xcode-select --install

Verify compiler installation:

# Check gcc
gcc --version
g++ --version

# Or check clang
clang --version

Troubleshooting (C++ Extensions)

1. tgn command not found

Ensure you've run the installation script and added tgn to PATH:

export PATH="/usr/local/ten_gn:$PATH"

2. Compilation failed: Compiler not found

Please refer to the "C++ Development Environment Requirements" section above to install the compiler.

Learn More

Troubleshooting

Python Library Loading Failure on macOS

Problem: Error indicating libpython3.10.dylib cannot be found when running the app

Solution:

export DYLD_LIBRARY_PATH=/usr/local/opt/python@3.10/Frameworks/Python.framework/Versions/3.10/lib:$DYLD_LIBRARY_PATH

Consider adding this line to your ~/.zshrc or ~/.bash_profile.

tman Download Failed or Slow

Problem: Network connection to GitHub is restricted

Solution:

  • Manual download: Visit the Releases page to download the tman binary for your platform

Port 8080 Already in Use

Problem: Port conflict error when starting the app

Solution:

  • Find the process using the port: lsof -i :8080 (macOS/Linux)
  • Kill the process: kill -9 <PID>
  • Or modify the port number in the app configuration file (transcriber_demo/ten_packages/extension/web_audio_control_go/property.json)

Go Build Failed

Problem: Go module related errors during build

Solution:

# Clean Go module cache
go clean -modcache

# Rebuild
cd transcriber_demo
tman run build

Python Dependencies Installation Failed

Problem: pip installation timeout or failure

Solution: Use a mirror source (for users in China)

pip3 install --index-url https://pypi.tuna.tsinghua.edu.cn/simple -r requirements.txt

Get Help

Edit on GitHub

Last Updated

Table of Contents

TEN Framework Quick Start Guide
System Requirements
Step 1: Check Your Environment
Python 3.10
Go 1.20+
Node.js / npm
Step 2: Install TEN Manager (tman)
Step 3: Create and Run the Demo App
Create App
Install Dependencies
Build the App
Configure Environment Variables
Run the App
Experience the Demo
Congratulations! 🎉
Understanding the App Architecture
Next Steps
Advanced: Developing and Building C++ Extensions
Install tgn Build Tool
Install C++ Extension
Compile C++ Extension
Run App with VAD Functionality
C++ Development Environment Requirements
Troubleshooting (C++ Extensions)
Learn More
Troubleshooting
Python Library Loading Failure on macOS
tman Download Failed or Slow
Port 8080 Already in Use
Go Build Failed
Python Dependencies Installation Failed
Get Help
TEN Framework Quick Start Guide | TEN Framework