### Install .Net on Linux

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/scripts/dotnet/notes.md

Download and install the .Net SDK on a Linux system using a script. Ensure the installation directory is added to the PATH environment variable.

```bash
wget https://dot.net/v1/dotnet-install.sh -O dotnet-install.sh
chmod +x dotnet-install.sh
./dotnet-install.sh --help
./dotnet-install.sh  --install-dir /star-fj/fangjun/software/dotnet
export PATH=/star-fj/fangjun/software/dotnet:$PATH

# Check that the installation is successful
which dotnet
dotnet --info

# To install the runtime, use
./dotnet-install.sh --runtime dotnet --install-dir /star-fj/fangjun/software/dotnet/
```

--------------------------------

### Enable FFmpeg Examples in Sherpa-NCNN Build

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/ffmpeg-examples/README.md

Enable FFmpeg examples during the Sherpa-NCNN build process by setting the appropriate CMake flag. Ensure FFmpeg is installed on your system.

```bash
cd sherpa-ncnn
mkdir -p build
cd build
cmake -DSHERPA_NCNN_ENABLE_FFMPEG_EXAMPLES=ON ..
make -j10
```

--------------------------------

### Install Node.js Dependencies

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/nodejs-examples/README.md

Run this command in the './nodejs-examples' directory to install necessary npm packages.

```bash
cd ./nodejs-examples
npm i
```

--------------------------------

### Install Dependencies

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/python-api-examples/AudioSer/README.md

Install the required Python packages using pip.

```python
pip install -r requirements.txt
```

--------------------------------

### Install WASM Build Artifacts

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/wasm/CMakeLists.txt

Installs the main executable, JavaScript glue code, HTML, and WASM files to the designated output directory. Also installs the data file if not building for NodeJS.

```cmake
install(
  TARGETS sherpa-ncnn-wasm-main DESTINATION bin/wasm
)

install(
  FILES
    "sherpa-ncnn.js"
    "app.js"
    "index.html"
    "$<TARGET_FILE_DIR:sherpa-ncnn-wasm-main>/sherpa-ncnn-wasm-main.js"
    "$<TARGET_FILE_DIR:sherpa-ncnn-wasm-main>/sherpa-ncnn-wasm-main.wasm"
  DESTINATION
    bin/wasm
)

if(NOT SHERPA_NCNN_ENABLE_WASM_FOR_NODEJS)
  install(
    FILES
      "$<TARGET_FILE_DIR:sherpa-ncnn-wasm-main>/sherpa-ncnn-wasm-main.data"
    DESTINATION
      bin/wasm
  )
endif()
```

--------------------------------

### Configure and Install Sherpa-NCNN pkg-config File

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/CMakeLists.txt

This snippet configures the sherpa-ncnn.pc file using a template and installs it to the destination directory. Ensure the template file exists at the specified path.

```cmake
configure_file(cmake/sherpa-ncnn.pc.in ${PROJECT_BINARY_DIR}/sherpa-ncnn.pc @ONLY)
install(
  FILES
    ${PROJECT_BINARY_DIR}/sherpa-ncnn.pc
  DESTINATION
    .
)
```

--------------------------------

### Install Python Package

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Install the Sherpa NCNN Python package using pip.

```bash
pip install sherpa-ncnn
```

--------------------------------

### Real-time Speech Recognition from Microphone with Node.js

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/nodejs-examples/README.md

Run this command in the './nodejs-examples' directory to start real-time speech recognition using a microphone.

```bash
cd ./nodejs-examples

node ./real-time-speech-recognition-microphone.js
```

--------------------------------

### Run AudioSer Service

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/python-api-examples/AudioSer/README.md

Start the AudioSer web service by running the main Python script.

```python
python AudioSer.py
```

--------------------------------

### Install Python Module

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/sherpa-ncnn/python/csrc/CMakeLists.txt

Installs the compiled '_sherpa_ncnn' Python module to the 'lib' directory within the installation prefix. This makes the module available for import in Python.

```cmake
install(TARGETS _sherpa_ncnn DESTINATION lib)
```

--------------------------------

### Install sherpa-ncnn-jni Library

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/sherpa-ncnn/jni/CMakeLists.txt

Installs the built sherpa-ncnn-jni shared library to the 'lib' directory. This makes the library available for use by other projects or applications.

```cmake
install(TARGETS sherpa-ncnn-jni DESTINATION lib)
```

--------------------------------

### Install FFmpeg on macOS

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/ffmpeg-examples/README.md

Install FFmpeg on macOS using the Homebrew package manager.

```bash
brew install ffmpeg
```

--------------------------------

### Go API Speech Recognition Example

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

This Go program demonstrates how to use the Sherpa-NCNN Go API to perform speech recognition on a WAV file. It includes configuration, audio processing, and result extraction. Ensure model files and 'test.wav' are in the correct paths.

```go
package main

import (
    "log"
    "os"

    sherpa "github.com/k2-fsa/sherpa-ncnn-go/sherpa_ncnn"
    "github.com/youpy/go-wav"
)

func main() {
    // Configure the recognizer
    config := sherpa.RecognizerConfig{
        Feat: sherpa.FeatureConfig{
            SampleRate: 16000,
            FeatureDim: 80,
        },
        Model: sherpa.ModelConfig{
            EncoderParam: "./model/encoder.ncnn.param",
            EncoderBin:   "./model/encoder.ncnn.bin",
            DecoderParam: "./model/decoder.ncnn.param",
            DecoderBin:   "./model/decoder.ncnn.bin",
            JoinerParam:  "./model/joiner.ncnn.param",
            JoinerBin:    "./model/joiner.ncnn.bin",
            Tokens:       "./model/tokens.txt",
            NumThreads:   4,
        },
        Decoder: sherpa.DecoderConfig{
            DecodingMethod: "greedy_search",
            NumActivePaths: 4,
        },
    }

    // Create recognizer
    recognizer := sherpa.NewRecognizer(&config)
    defer sherpa.DeleteRecognizer(recognizer)

    // Create stream
    stream := sherpa.NewStream(recognizer)
    defer sherpa.DeleteStream(stream)

    // Read WAV file
    samples, sampleRate := readWave("test.wav")

    // Process audio
    stream.AcceptWaveform(sampleRate, samples)

    // Add tail padding
    tailPadding := make([]float32, int(float32(sampleRate)*0.3))
    stream.AcceptWaveform(sampleRate, tailPadding)

    // Decode
    for recognizer.IsReady(stream) {
        recognizer.Decode(stream)
    }

    // Get result
    result := recognizer.GetResult(stream)
    log.Printf("Result: %s", result.Text)
    log.Printf("Duration: %.2f seconds", float32(len(samples))/float32(sampleRate))
}

func readWave(filename string) ([]float32, int) {
    file, _ := os.Open(filename)
    defer file.Close()

    reader := wav.NewReader(file)
    format, _ := reader.Format()

    reader.Duration()
    buf := make([]byte, reader.Size)
    reader.Read(buf)

    // Convert int16 to float32
    numSamples := len(buf) / 2
    samples := make([]float32, numSamples)
    for i := 0; i < numSamples; i++ {
        s16 := int16(buf[i*2]) | int16(buf[i*2+1])<<8
        samples[i] = float32(s16) / 32768.0
    }

    return samples, int(format.SampleRate)
}

```

--------------------------------

### Build WebAssembly

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Build Sherpa NCNN for WebAssembly. Requires Emscripten to be installed and configured.

```bash
mkdir build-wasm && cd build-wasm
emcmake cmake .. -DSHERPA_NCNN_ENABLE_WASM=ON
emmake make -j$(nproc)
```

--------------------------------

### Add Sherpa-ncnn and Example Subdirectories

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/CMakeLists.txt

Adds the main Sherpa-ncnn source directory and optional example subdirectories to the build. This command is used to incorporate code from other directories into the main build process.

```cmake
add_subdirectory(sherpa-ncnn)

if(SHERPA_NCNN_ENABLE_FFMPEG_EXAMPLES)
  add_subdirectory(ffmpeg-examples)
endif()

if(SHERPA_NCNN_ENABLE_C_API AND SHERPA_NCNN_ENABLE_BINARY)
  add_subdirectory(c-api-examples)
endif()

if(SHERPA_NCNN_ENABLE_WASM)
  add_subdirectory(wasm)
endif()
```

--------------------------------

### Build with Vulkan GPU Support

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Build Sherpa NCNN with Vulkan GPU acceleration. Requires the Vulkan SDK to be installed.

```bash
cmake .. -DNCNN_VULKAN=ON
make -j$(nproc)
```

--------------------------------

### API Response Example (English)

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/python-api-examples/AudioSer/README.md

A successful API response for speech-to-text conversion, returning a JSON object with status and message.

```json
{
    "status": 200, 
    "message": "helloworld"
}
```

--------------------------------

### Download and Extract Sherpa-NCNN Model

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/wasm/assets/README.md

Use these commands to download a specific Sherpa-NCNN model, extract its contents, and move the necessary files to the current directory. Ensure you have `wget` and `tar` installed.

```shell
cd /path/to/this/directory
wget -q https://github.com/k2-fsa/sherpa-ncnn/releases/download/models/sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
tar xf sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
rm sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
mv sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13/*pnnx.ncnn.param .
mv sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13/*pnnx.ncnn.bin .
mv sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13/tokens.txt .
```

--------------------------------

### Fix: libavdevice not found

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/ffmpeg-examples/README.md

Install the libavdevice development package on Debian/Ubuntu systems to resolve the 'libavdevice was not found' error.

```bash
sudo apt-get install libavdevice-dev
```

--------------------------------

### API Response Example (Chinese)

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/python-api-examples/AudioSer/README.md

A successful API response for speech-to-text conversion, returning a JSON object with status and message.

```json
{
    "status": 200, 
    "message": "你好世界"
}
```

--------------------------------

### C API Speech Recognition Example

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

This C code demonstrates how to use the Sherpa-NCNN C API to perform speech recognition on a WAV file. It includes configuration of the recognizer, processing audio chunks, and retrieving intermediate and final results. Ensure model files and 'test.wav' are in the correct paths.

```c
#include <stdio.h>
#include <stdlib.h>
#include <string.h>
#include "sherpa-ncnn/c-api/c-api.h"

int main() {
    // Configure the recognizer
    SherpaNcnnRecognizerConfig config;
    memset(&config, 0, sizeof(config));

    // Model paths
    config.model_config.tokens = "./model/tokens.txt";
    config.model_config.encoder_param = "./model/encoder.ncnn.param";
    config.model_config.encoder_bin = "./model/encoder.ncnn.bin";
    config.model_config.decoder_param = "./model/decoder.ncnn.param";
    config.model_config.decoder_bin = "./model/decoder.ncnn.bin";
    config.model_config.joiner_param = "./model/joiner.ncnn.param";
    config.model_config.joiner_bin = "./model/joiner.ncnn.bin";
    config.model_config.num_threads = 4;
    config.model_config.use_vulkan_compute = 0;  // 1 to enable GPU

    // Decoder settings
    config.decoder_config.decoding_method = "greedy_search";
    config.decoder_config.num_active_paths = 4;

    // Feature extractor settings
    config.feat_config.sampling_rate = 16000;
    config.feat_config.feature_dim = 80;

    // Endpoint detection (optional)
    config.enable_endpoint = 0;
    config.rule1_min_trailing_silence = 2.4;
    config.rule2_min_trailing_silence = 1.2;
    config.rule3_min_utterance_length = 300;

    // Create recognizer and stream
    SherpaNcnnRecognizer *recognizer = CreateRecognizer(&config);
    SherpaNcnnStream *stream = CreateStream(recognizer);
    SherpaNcnnDisplay *display = CreateDisplay(50);  // max 50 words per line

    // Read and process WAV file (assuming 16-bit PCM, 16kHz)
    FILE *fp = fopen("test.wav", "rb");
    fseek(fp, 44, SEEK_SET);  // Skip WAV header

    #define CHUNK_SIZE 3200  // 0.2 seconds at 16kHz
    int16_t buffer[CHUNK_SIZE];
    float samples[CHUNK_SIZE];

    while (!feof(fp)) {
        size_t n = fread(buffer, sizeof(int16_t), CHUNK_SIZE, fp);
        if (n > 0) {
            // Convert int16 to float32 normalized to [-1, 1]
            for (size_t i = 0; i < n; ++i) {
                samples[i] = buffer[i] / 32768.0f;
            }

            // Feed audio to stream
            AcceptWaveform(stream, 16000, samples, n);

            // Decode when ready
            while (IsReady(recognizer, stream)) {
                Decode(recognizer, stream);
            }

            // Get and display intermediate result
            SherpaNcnnResult *result = GetResult(recognizer, stream);
            if (strlen(result->text) > 0) {
                SherpaNcnnPrint(display, 0, result->text);
            }
            DestroyResult(result);
        }
    }
    fclose(fp);

    // Add tail padding and finalize
    float tail_paddings[4800] = {0};  // 0.3 seconds
    AcceptWaveform(stream, 16000, tail_paddings, 4800);
    InputFinished(stream);

    // Final decode
    while (IsReady(recognizer, stream)) {
        Decode(recognizer, stream);
    }

    // Get final result
    SherpaNcnnResult *result = GetResult(recognizer, stream);
    printf("\nFinal: %s\n", result->text);
    DestroyResult(result);

    // Cleanup
    DestroyDisplay(display);
    DestroyStream(stream);
    DestroyRecognizer(recognizer);

    return 0;
}

```

--------------------------------

### Include Project Source Directory

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/sherpa-ncnn/python/csrc/CMakeLists.txt

Includes the project's source directory for CMake to find files. This is a common setup for CMake projects.

```cmake
include_directories(${PROJECT_SOURCE_DIR})
```

--------------------------------

### Build with Python Bindings and Shared Libraries

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Build Sherpa NCNN with Python bindings enabled and shared libraries. Ensure Python is installed.

```bash
cmake .. -DSHERPA_NCNN_ENABLE_PYTHON=ON -DBUILD_SHARED_LIBS=ON
make -j$(nproc)
```

--------------------------------

### CMake Build Configuration for sherpa-ncnn-ffmpeg

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/ffmpeg-examples/CMakeLists.txt

This CMake script sets up the build for the sherpa-ncnn-ffmpeg executable. It includes linking against the sherpa-ncnn C API and various FFmpeg libraries. Ensure FFmpeg development packages are installed and discoverable by PkgConfig.

```cmake
include_directories(${CMAKE_SOURCE_DIR})
add_executable(sherpa-ncnn-ffmpeg sherpa-ncnn-ffmpeg.cc)

# Link libraries from sherpa-ncnn.
target_link_libraries(sherpa-ncnn-ffmpeg sherpa-ncnn-c-api)

find_package(PkgConfig REQUIRED)
pkg_check_modules(AVCODEC REQUIRED libavcodec)
include_directories(${AVCODEC_INCLUDE_DIRS})
target_link_directories(sherpa-ncnn-ffmpeg PRIVATE ${AVCODEC_LIBRARY_DIRS})
# All libraries of FFmpeg shares the same include and library directory.
# Note that ${AVCODEC_LIBRARIES} equals to avcodec, but we add it for consistence.
target_link_libraries(sherpa-ncnn-ffmpeg avformat avfilter avcodec avutil swresample swscale avdevice)
```

--------------------------------

### Check for Alsa Header and Define Macro

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/CMakeLists.txt

Checks if the 'alsa/asoundlib.h' header is available on UNIX-like systems (excluding macOS) when building binaries. If found, it defines SHERPA_NCNN_ENABLE_ALSA; otherwise, it issues a warning with instructions to install the necessary development files.

```cmake
if(SHERPA_NCNN_ENABLE_BINARY AND UNIX AND NOT APPLE)
  include(CheckIncludeFileCXX)
  check_include_file_cxx(alsa/asoundlib.h SHERPA_NCNN_HAS_ALSA)
  if(SHERPA_NCNN_HAS_ALSA)
    message(STATUS "With Alsa")
    add_definitions(-DSHERPA_NCNN_ENABLE_ALSA=1)
  elseif(UNIX AND NOT APPLE)
    message(WARNING "\
  Could not find alsa/asoundlib.h ! 
  We won't build sherpa-ncnn-alsa
  To fix that, please do:
    (1) sudo apt-get install alsa-utils libasound2-dev
    (2) rm -rf build
    (3) re-try
  ")
  endif()
endif()
```

--------------------------------

### Python Offline Recognition with SenseVoice Model

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Use this snippet for non-streaming speech recognition on pre-recorded audio files. It supports SenseVoice models for multilingual recognition and can optionally perform inverse text normalization (ITN). Ensure soundfile is installed.

```python
import time
import sherpa_ncnn
import soundfile as sf

def create_offline_recognizer():
    config = sherpa_ncnn.OfflineRecognizerConfig(
        model_config=sherpa_ncnn.OfflineModelConfig(
            sense_voice=sherpa_ncnn.OfflineSenseVoiceModelConfig(
                model_dir="./sherpa-ncnn-sense-voice-zh-en-ja-ko-yue-2024-07-17",
                use_itn=True,  # Enable inverse text normalization
            ),
            tokens="./sherpa-ncnn-sense-voice-zh-en-ja-ko-yue-2024-07-17/tokens.txt",
            num_threads=2,
            debug=True,
        )
    )

    if not config.validate():
        raise ValueError("Invalid configuration")

    return sherpa_ncnn.OfflineRecognizer(config)

def main():
    recognizer = create_offline_recognizer()

    # Read audio file
    wave_filename = "./test_wavs/en.wav"
    audio, sample_rate = sf.read(wave_filename, dtype="float32", always_2d=True)
    audio = audio[:, 0]  # Use first channel only

    # Process the entire audio at once
    start_time = time.time()

    stream = recognizer.create_stream()
    stream.accept_waveform(sample_rate, audio)
    recognizer.decode_stream(stream)

    elapsed = time.time() - start_time

    # Get results
    result = stream.result
    print(f"Text: {result.text}")

    # Calculate real-time factor
    duration = len(audio) / sample_rate
    rtf = elapsed / duration
    print(f"Audio duration: {duration:.3f}s, Processing time: {elapsed:.3f}s, RTF: {rtf:.3f}")

if __name__ == "__main__":
    main()

```

--------------------------------

### Python Real-Time Microphone Recognition with Endpoint Detection

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Use this snippet for continuous speech recognition from a microphone. It leverages endpoint detection to automatically segment speech, enabling a conversational interaction pattern. Ensure the sounddevice library is installed.

```python
import sounddevice as sd
import sherpa_ncnn

def create_recognizer():
    return sherpa_ncnn.Recognizer(
        tokens="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/tokens.txt",
        encoder_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/encoder_jit_trace-pnnx.ncnn.param",
        encoder_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/encoder_jit_trace-pnnx.ncnn.bin",
        decoder_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/decoder_jit_trace-pnnx.ncnn.param",
        decoder_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/decoder_jit_trace-pnnx.ncnn.bin",
        joiner_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/joiner_jit_trace-pnnx.ncnn.param",
        joiner_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/joiner_jit_trace-pnnx.ncnn.bin",
        num_threads=4,
        decoding_method="modified_beam_search",
        enable_endpoint_detection=True,
        rule1_min_trailing_silence=2.4,  # endpoint after 2.4s silence (no decoded content)
        rule2_min_trailing_silence=1.2,  # endpoint after 1.2s silence (with decoded content)
        rule3_min_utterance_length=300,  # max utterance length in seconds
        hotwords_file="",
        hotwords_score=1.5,
    )

def main():
    recognizer = create_recognizer()
    sample_rate = recognizer.sample_rate
    samples_per_read = int(0.1 * sample_rate)  # 100ms chunks
    segment_id = 0
    last_result = ""

    print("Listening... Press Ctrl+C to stop")

    with sd.InputStream(channels=1, dtype="float32", samplerate=sample_rate) as stream:
        while True:
            samples, _ = stream.read(samples_per_read)
            samples = samples.reshape(-1)
            recognizer.accept_waveform(sample_rate, samples)

            result = recognizer.text

            # Print partial results as they update
            if result and result != last_result:
                last_result = result
                print(f"\r{segment_id}: {result}", end="", flush=True)

            # Check for endpoint (speech segment completed)
            if recognizer.is_endpoint:
                if result:
                    print(f"\r{segment_id}: {result}")
                    segment_id += 1
                recognizer.reset()  # Reset for next segment
                last_result = ""

if __name__ == "__main__":
    try:
        main()
    except KeyboardInterrupt:
        print("\nStopped")

```

--------------------------------

### Configure Sherpa-NCNN C API Library

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/sherpa-ncnn/c-api/CMakeLists.txt

This CMake script configures the build for the sherpa-ncnn-c-api library. It includes the source directory, adds the library target, links it against the core library, and sets compile definitions based on whether shared libraries are being built. Finally, it specifies installation targets for the library and header files.

```cmake
include_directories(${CMAKE_SOURCE_DIR})
add_library(sherpa-ncnn-c-api c-api.cc)
target_link_libraries(sherpa-ncnn-c-api sherpa-ncnn-core)

if(BUILD_SHARED_LIBS)
  target_compile_definitions(sherpa-ncnn-c-api PRIVATE SHERPA_NCNN_BUILD_SHARED_LIBS=1)
  target_compile_definitions(sherpa-ncnn-c-api PRIVATE SHERPA_NCNN_BUILD_MAIN_LIB=1)
endif()

install(TARGETS sherpa-ncnn-c-api DESTINATION lib)

install(FILES c-api.h
  DESTINATION include/sherpa-ncnn/c-api
)
```

--------------------------------

### Create and Configure a .Net Project for Sherpa-ncnn

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/scripts/dotnet/notes.md

Set up a new .Net solution and console application, then add the sherpa-ncnn nuget package. Always use the latest version of the package.

```bash
cd /tmp
mkdir hello
cd hello
dotnet new sln

dotnet new console -o test-sherpa-ncnn


dotnet sln add ./test-sherpa-ncnn/test-sherpa-ncnn.csproj
cd test-sherpa-ncnn

# please always use the latest version.
dotnet add package org.k2fsa.sherpa.ncnn -v 1.9.0
```

--------------------------------

### List Available Nuget Sources

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/scripts/dotnet/notes.md

Command to display all configured nuget package sources.

```bash
dotnet nuget list source
```

--------------------------------

### Decode Audio File with Node.js

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/nodejs-examples/README.md

Execute this command in the './nodejs-examples' directory to run the script for decoding an audio file using sherpa-ncnn.

```bash
cd ./nodejs-examples

node ./decode-file.js
```

--------------------------------

### Configure and Use Voice Activity Detector (VAD) in C++

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Demonstrates setting up the Silero VAD model configuration, including model directory, speech thresholds, and window size. It shows how to process audio in chunks, detect speech segments, and handle them using the VoiceActivityDetector class.

```cpp
#include "sherpa-ncnn/csrc/voice-activity-detector.h"
#include "sherpa-ncnn/csrc/silero-vad-model-config.h"

int main() {
    using namespace sherpa_ncnn;

    // Configure Silero VAD model
    SileroVadModelConfig config;
    config.model_dir = "./silero-vad-model";
    config.threshold = 0.5f;              // Speech probability threshold
    config.min_silence_duration = 0.5f;   // Minimum silence to end segment (seconds)
    config.min_speech_duration = 0.25f;   // Minimum speech duration (seconds)
    config.window_size = 512;             // Samples per window (512 for 16kHz)
    config.sample_rate = 16000;
    config.num_threads = 1;
    config.use_vulkan_compute = false;

    if (!config.Validate()) {
        fprintf(stderr, "Invalid VAD configuration\n");
        return 1;
    }

    // Create VAD with 60-second buffer
    VoiceActivityDetector vad(config, 60.0f);

    // Process audio in chunks (512 samples at a time for 16kHz)
    float samples[512];
    // ... read samples from audio source ...

    while (/* has more audio */) {
        // Feed samples to VAD
        vad.AcceptWaveform(samples, 512);

        // Check if currently in speech
        if (vad.IsSpeechDetected()) {
            printf("Speech detected\n");
        }

        // Process detected speech segments
        while (!vad.Empty()) {
            const SpeechSegment& segment = vad.Front();

            // segment.start is the start position in samples
            // segment.samples contains the speech audio
            printf("Speech segment: start=%d, samples=%zu\n",
                   segment.start, segment.samples.size());

            // Process segment (e.g., send to recognizer)
            // ...

            vad.Pop();  // Remove processed segment
        }
    }

    // Flush remaining audio at end of stream
    vad.Flush();

    // Process any remaining segments
    while (!vad.Empty()) {
        const SpeechSegment& segment = vad.Front();
        // ... process segment ...
        vad.Pop();
    }

    // Reset for reuse
    vad.Reset();

    return 0;
}

```

--------------------------------

### Initialize SherpaNcnn Recognizer in Kotlin

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Sets up the SherpaNcnn recognizer with feature extraction, model, and decoder configurations. Loads models from APK assets and supports GPU acceleration via Vulkan.

```kotlin
package com.example.speechrecognition

import android.content.res.AssetManager
import com.k2fsa.sherpa.ncnn.*

class SpeechRecognizer(private val assetManager: AssetManager) {
    private lateinit var sherpa: SherpaNcnn

    fun initialize() {
        // Feature extractor config
        val featConfig = FeatureExtractorConfig(
            sampleRate = 16000f,
            featureDim = 80
        )

        // Model config (paths relative to assets folder)
        val modelDir = "sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13"
        val modelConfig = ModelConfig(
            encoderParam = "$modelDir/encoder.ncnn.param",
            encoderBin = "$modelDir/encoder.ncnn.bin",
            decoderParam = "$modelDir/decoder.ncnn.param",
            decoderBin = "$modelDir/decoder.ncnn.bin",
            joinerParam = "$modelDir/joiner.ncnn.param",
            joinerBin = "$modelDir/joiner.ncnn.bin",
            tokens = "$modelDir/tokens.txt",
            numThreads = 2,
            useGPU = true  // Enable Vulkan GPU acceleration if available
        )

        // Decoder config
        val decoderConfig = DecoderConfig(
            method = "modified_beam_search",
            numActivePaths = 4
        )

        // Full recognizer config with endpoint detection
        val config = RecognizerConfig(
            featConfig = featConfig,
            modelConfig = modelConfig,
            decoderConfig = decoderConfig,
            enableEndpoint = true,
            rule1MinTrailingSilence = 2.4f,
            rule2MinTrailingSilence = 1.0f,
            rule3MinUtteranceLength = 30.0f,
            hotwordsFile = "",
            hotwordsScore = 1.5f
        )

        // Create recognizer with asset manager for loading from APK
        sherpa = SherpaNcnn(config, assetManager)
    }

    fun processAudio(samples: FloatArray) {
        sherpa.acceptSamples(samples)

        while (sherpa.isReady()) {
            sherpa.decode()
        }
    }

    fun getText(): String = sherpa.text

    fun isEndpoint(): Boolean = sherpa.isEndpoint()

    fun reset() {
        sherpa.reset(recreate = false)
    }

    fun inputFinished() {
        sherpa.inputFinished()
    }
}

// Usage in Activity
class MainActivity : AppCompatActivity() {
    private lateinit var recognizer: SpeechRecognizer

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        recognizer = SpeechRecognizer(assets)
        recognizer.initialize()

        // Process audio from AudioRecord or file
        // val samples: FloatArray = ... // normalized to [-1, 1]
        // recognizer.processAudio(samples)
        // val text = recognizer.getText()
    }
}

```

--------------------------------

### Basic Build (CPU Only, Static Libraries)

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Perform a basic build of Sherpa NCNN using CMake. This configuration enables CPU-only processing and static libraries.

```bash
mkdir build && cd build
cmake ..
make -j$(nproc)
```

--------------------------------

### Verify Model File Structure

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/wasm/assets/README.md

This command displays the expected file structure after successfully preparing the model assets. Ensure all listed files are present before proceeding with builds.

```shell
assets fangjun$ tree .
.
├── README.md
├── decoder_jit_trace-pnnx.ncnn.bin
├── decoder_jit_trace-pnnx.ncnn.param
├── encoder_jit_trace-pnnx.ncnn.bin
├── encoder_jit_trace-pnnx.ncnn.param
├── joiner_jit_trace-pnnx.ncnn.bin
├── joiner_jit_trace-pnnx.ncnn.param
└── tokens.txt

0 directories, 8 files
```

--------------------------------

### Publish Nuget Packages

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/scripts/dotnet/notes.md

Push nuget packages to a nuget repository using an API key. Ensure the correct package file and API key are specified.

```bash
export MY_API_KEY=xxxxxx
dotnet nuget push ./org.k2fsa.sherpa.ncnn.runtime.osx-x64.1.8.2.nupkg --api-key $MY_API_KEY --source https://api.nuget.org/v3/index.json
dotnet nuget push ./org.k2fsa.sherpa.ncnn.1.8.2.nupkg --api-key $MY_API_KEY --source https://api.nuget.org/v3/index.json
```

--------------------------------

### Fix: ModuleNotFoundError: No module named 'apt_pkg'

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/ffmpeg-examples/README.md

Install the python-apt package on Debian/Ubuntu systems to resolve the 'ModuleNotFoundError: No module named 'apt_pkg'' error.

```bash
sudo apt-get install python-apt
```

--------------------------------

### Perform Text-to-Speech Synthesis in C++

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Shows how to initialize and use the `OfflineTts` class for text-to-speech synthesis with VITS models. Includes configuration for model paths, synthesis parameters like speaker ID and speed, and saving the generated audio to a WAV file.

```cpp
#include "sherpa-ncnn/csrc/offline-tts.h"
#include "sherpa-ncnn/csrc/wave-writer.h"
#include <iostream>

int main() {
    using namespace sherpa_ncnn;

    // Configure TTS model
    OfflineTtsVitsModelConfig vits_config;
    vits_config.model_dir = "./ncnn-vits-piper-en_US-bryce-medium-fp16";

    OfflineTtsModelConfig model_config;
    model_config.vits = vits_config;
    model_config.num_threads = 2;
    model_config.debug = false;

    OfflineTtsConfig config;
    config.model = model_config;
    config.max_num_sentences = 1;      // Process one sentence at a time
    config.silence_scale = 1.0f;       // Scale pauses between sentences

    if (!config.Validate()) {
        std::cerr << "Invalid TTS configuration\n";
        return 1;
    }

    // Create TTS engine
    OfflineTts tts(config);

    std::cout << "Sample rate: " << tts.SampleRate() << "\n";
    std::cout << "Number of speakers: " << tts.NumSpeakers() << "\n";

    // Configure synthesis arguments
    TtsArgs args;
    args.text = "Hello world. This is a text to speech demonstration.";
    args.sid = 0;              // Speaker ID (for multi-speaker models)
    args.speed = 1.0f;         // Speech speed (1.0 = normal)
    args.noise_scale = 0.667f;
    args.noise_scale_w = 0.8f;

    // Optional: Callback for streaming output
    auto callback = [](const float* samples, int32_t num_samples, 
                       int32_t processed, int32_t total, void* arg) -> int32_t {
        std::cout << "Progress: " << processed << "/" << total << " sentences\n";
        // Return 1 to continue, 0 to stop
        return 1;
    };

    // Generate audio
    GeneratedAudio audio = tts.Generate(args, callback, nullptr);

    if (audio.samples.empty()) {
        std::cerr << "Failed to generate audio\n";
        return 1;
    }

    // Save to WAV file
    std::string output_file = "output.wav";
    bool ok = WriteWave(output_file, audio.sample_rate, audio.samples.data(),
                        audio.samples.size());

    if (ok) {
        float duration = static_cast<float>(audio.samples.size()) / audio.sample_rate;
        std::cout << "Saved to " << output_file << "\n";
        std::cout << "Duration: " << duration << " seconds\n";
    }

    return 0;
}

```

--------------------------------

### Hotwords Decode Audio File with Node.js

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/nodejs-examples/README.md

Execute this command in the './nodejs-examples' directory to run the script for decoding an audio file with hotword detection.

```bash
cd ./nodejs-examples

node ./hotwords-decode-file.js
```

--------------------------------

### Create Sherpa-NCNN Recognizer in Node.js

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Initializes the sherpa-ncnn recognizer with model and decoding configurations. Ensure model files are correctly path-ed. Uses WebAssembly for in-browser or Node.js environments.

```javascript
const fs = require('fs');
const wav = require('wav');
const { Readable } = require('stream');
const sherpa_ncnn = require('sherpa-ncnn');

function createRecognizer() {
    const modelConfig = {
        encoderParam: './model/encoder.ncnn.param',
        encoderBin: './model/encoder.ncnn.bin',
        decoderParam: './model/decoder.ncnn.param',
        decoderBin: './model/decoder.ncnn.bin',
        joinerParam: './model/joiner.ncnn.param',
        joinerBin: './model/joiner.ncnn.bin',
        tokens: './model/tokens.txt',
        useVulkanCompute: 0,
        numThreads: 1,
    };

    const decoderConfig = {
        decodingMethod: 'greedy_search',
        numActivePaths: 4,
    };

    const featConfig = {
        samplingRate: 16000,
        featureDim: 80,
    };

    const config = {
        featConfig: featConfig,
        modelConfig: modelConfig,
        decoderConfig: decoderConfig,
        enableEndpoint: 1,
        rule1MinTrailingSilence: 1.2,
        rule2MinTrailingSilence: 2.4,
        rule3MinUtternceLength: 20,
    };

    return sherpa_ncnn.createRecognizer(config);
}
```

--------------------------------

### Download and Extract Pre-trained Models

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Download and extract pre-trained models for Sherpa NCNN.

```bash
wget https://github.com/k2-fsa/sherpa-ncnn/releases/download/models/sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
tar xvf sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
```

--------------------------------

### Download and Extract Sherpa-NCNN Model

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/nodejs-examples/README.md

Download a pre-trained model from the Sherpa-NCNN releases, extract it, and then remove the archive. Ensure you are in the './nodejs-examples' directory.

```bash
cd ./nodejs-examples
wget https://github.com/k2-fsa/sherpa-ncnn/releases/download/models/sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
tar xvf sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
rm sherpa-ncnn-streaming-zipformer-bilingual-zh-en-2023-02-13.tar.bz2
```

--------------------------------

### Download and Configure Linaro ARM GCC 7.5 Toolchain

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/toolchains/README.md

Downloads the Linaro GCC 7.5 toolchain for aarch64, extracts it to a specified directory, and updates the PATH. This is useful for aarch64 cross-compilation.

```bash
wget https://releases.linaro.org/components/toolchain/binaries/latest-7/aarch64-linux-gnu/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu.tar.xz

tar xvf gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu.tar.xz -C /ceph-fj/fangjun/software

export PATH=/ceph-fj/fangjun/software/gcc-linaro-7.5.0-2019.12-x86_64_aarch64-linux-gnu/bin:$PATH
```

--------------------------------

### Swift Speech Recognition Workflow

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Demonstrates a full speech recognition workflow using Sherpa-NCNN in Swift. This includes configuring feature extractors, models, decoders, and the recognizer, then processing an audio file and retrieving the recognized text. Ensure model files and the audio file exist at the specified paths.

```swift
func runRecognition() {
    // Configure feature extractor
    let featConfig = sherpaNcnnFeatureExtractorConfig(
        sampleRate: 16000,
        featureDim: 80
    )

    // Configure model paths
    let modelConfig = sherpaNcnnModelConfig(
        encoderParam: "./model/encoder.ncnn.param",
        encoderBin: "./model/encoder.ncnn.bin",
        decoderParam: "./model/decoder.ncnn.param",
        decoderBin: "./model/decoder.ncnn.bin",
        joinerParam: "./model/joiner.ncnn.param",
        joinerBin: "./model/joiner.ncnn.bin",
        tokens: "./model/tokens.txt",
        numThreads: 4,
        useVulkanCompute: false
    )

    // Configure decoder
    let decoderConfig = sherpaNcnnDecoderConfig(
        decodingMethod: "modified_beam_search",
        numActivePaths: 4
    )

    // Create recognizer config with endpoint detection
    var config = sherpaNcnnRecognizerConfig(
        featConfig: featConfig,
        modelConfig: modelConfig,
        decoderConfig: decoderConfig,
        enableEndpoint: true,
        rule1MinTrailingSilence: 2.4,
        rule2MinTrailingSilence: 1.2,
        rule3MinUtteranceLength: 30,
        hotwordsFile: "",
        hotwordsScore: 1.5
    )

    // Create recognizer
    let recognizer = SherpaNcnnRecognizer(config: &config)

    // Load audio file
    let fileURL = URL(fileURLWithPath: "./test.wav")
    let audioFile = try! AVAudioFile(forReading: fileURL)
    let audioFormat = audioFile.processingFormat

    // Read audio samples
    let frameCount = UInt32(audioFile.length)
    let buffer = AVAudioPCMBuffer(pcmFormat: audioFormat, frameCapacity: frameCount)!
    try! audioFile.read(into: buffer)

    // Feed samples to recognizer
    let samples = buffer.array()
    recognizer.acceptWaveform(samples: samples, sampleRate: 16000)

    // Add tail padding
    let tailPadding = [Float](repeating: 0.0, count: 3200)
    recognizer.acceptWaveform(samples: tailPadding, sampleRate: 16000)

    // Signal end of input
    recognizer.inputFinished()

    // Decode
    while recognizer.isReady() {
        recognizer.decode()
    }

    // Get result
    let result = recognizer.getResult()
    print("Result: \(result.text)")
}
```

--------------------------------

### Define Extra Libraries for Pkg-Config

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/CMakeLists.txt

Sets up extra libraries to be used with pkg-config, particularly for static builds on different platforms. This ensures correct linking when generating package information.

```cmake
set(SHERPA_NCNN_PKG_CONFIG_EXTRA_LIBS)

if(NOT BUILD_SHARED_LIBS)
  if(APPLE)
    set(SHERPA_NCNN_PKG_CONFIG_EXTRA_LIBS "-lomp -lc++")
  endif()

  if(UNIX AND NOT APPLE)
    set(SHERPA_NCNN_PKG_CONFIG_EXTRA_LIBS "-lm -lstdc++ -fopenmp")
  endif()
endif()
```

--------------------------------

### Build decode-file-c-api with Sherpa-ncnn

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/c-api-examples/CMakeLists.txt

This CMake script configures the build for the decode-file-c-api executable. It includes the source directory, adds the executable, and links it with the sherpa-ncnn-c-api library.

```cmake
include_directories(${CMAKE_SOURCE_DIR})
add_executable(decode-file-c-api decode-file-c-api.c)
target_link_libraries(decode-file-c-api sherpa-ncnn-c-api)
```

--------------------------------

### Python Streaming Speech Recognition with Sherpa NCNN

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Demonstrates how to perform streaming speech recognition using the Python Recognizer class. This snippet shows initialization with model files, processing audio in chunks, and retrieving intermediate and final recognition results. Ensure model files are correctly path-ed and audio is in the expected format.

```Python
import wave
import numpy as np
import sherpa_ncnn

# Initialize the streaming recognizer with model files
recognizer = sherpa_ncnn.Recognizer(
    tokens="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/tokens.txt",
    encoder_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/encoder_jit_trace-pnnx.ncnn.param",
    encoder_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/encoder_jit_trace-pnnx.ncnn.bin",
    decoder_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/decoder_jit_trace-pnnx.ncnn.param",
    decoder_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/decoder_jit_trace-pnnx.ncnn.bin",
    joiner_param="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/joiner_jit_trace-pnnx.ncnn.param",
    joiner_bin="./sherpa-ncnn-conv-emformer-transducer-2022-12-06/joiner_jit_trace-pnnx.ncnn.bin",
    num_threads=4,
    decoding_method="greedy_search",  # or "modified_beam_search"
    num_active_paths=4,  # used only for modified_beam_search
    enable_endpoint_detection=False,
    rule1_min_trailing_silence=2.4,
    rule2_min_trailing_silence=1.2,
    rule3_min_utterance_length=20,
    hotwords_file="",  # optional hotwords file path
    hotwords_score=1.5,
)

# Read and process audio file
filename = "./test_wavs/audio.wav"
with wave.open(filename) as f:
    sample_rate = f.getframerate()
    num_samples = f.getnframes()
    samples = f.readframes(num_samples)
    samples_int16 = np.frombuffer(samples, dtype=np.int16)
    samples_float32 = samples_int16.astype(np.float32) / 32768  # Normalize to [-1, 1]

# Simulate streaming by processing in chunks
chunk_size = int(0.1 * sample_rate)  # 100ms chunks
for start in range(0, len(samples_float32), chunk_size):
    end = min(start + chunk_size, len(samples_float32))
    recognizer.accept_waveform(sample_rate, samples_float32[start:end])

    # Get intermediate results
    if recognizer.text:
        print(f"Partial: {recognizer.text}")

# Add tail padding and finalize
tail_paddings = np.zeros(int(sample_rate * 0.5), dtype=np.float32)
recognizer.accept_waveform(sample_rate, tail_paddings)
recognizer.input_finished()

# Get final result
print(f"Final text: {recognizer.text}")
print(f"Tokens: {recognizer.tokens}")
print(f"Timestamps: {recognizer.timestamps}")

```

--------------------------------

### Swift Audio Buffer Conversion Helper

Source: https://context7.com/k2-fsa/sherpa-ncnn/llms.txt

Provides an extension to convert AVAudioPCMBuffer to a [Float] array for easier processing. Ensure the audio buffer has float channel data.

```swift
import AVFoundation

// Helper extension for audio buffer conversion
extension AVAudioPCMBuffer {
    func array() -> [Float] {
        return Array(UnsafeBufferPointer(start: self.floatChannelData?[0],
                                          count: Int(self.frameLength)))
    }
}
```

--------------------------------

### Create Python Module with pybind11

Source: https://github.com/k2-fsa/sherpa-ncnn/blob/master/sherpa-ncnn/python/csrc/CMakeLists.txt

Creates a Python extension module named '_sherpa_ncnn' using pybind11 and the specified source files. Ensure pybind11 is correctly configured in your CMakeLists.txt.

```cmake
pybind11_add_module(_sherpa_ncnn ${srcs})
```