Examples

Each example below is a complete, runnable snippet. Replace the placeholder model name with a value provided during onboarding.

Minimal real-time enhancement

The smallest possible integration: feed one chunk through Orpheus.

import os
import numpy as np
from hecttor_sdk import ASRSpeechEnhancer, ASRSpeechEnhancerConfig, ModelConfig

config = ASRSpeechEnhancerConfig(
    api_key=os.environ["HECTTOR_API_KEY"],
    model_config=ModelConfig(model_name="your_model"),
    chunk_size_ms=20,
    sample_rate=16000,
)

enhancer = ASRSpeechEnhancer()
success, error = enhancer.initialize(config)
if not success:
    raise RuntimeError(f"Initialization failed: {error}")

chunk_size = enhancer.get_chunk_size_samples()
audio_chunk = np.random.randn(chunk_size).astype(np.float32)
enhanced, error = enhancer.process_chunk(audio_chunk)
if enhanced is None:
    raise RuntimeError(f"Processing failed: {error}")

const { ASRSpeechEnhancer } = require('hecttor_sdk');

async function main() {
  const enhancer = new ASRSpeechEnhancer();
  await enhancer.initialize({
    apiKey: 'your_api_key_here',
    chunkSizeMs: 20,
    sampleRate: 16000,
    modelConfig: { modelName: 'your_model' },
  });

  const chunkSize = enhancer.getChunkSizeSamples();
  const audioChunk = new Float32Array(chunkSize);
  const enhanced = await enhancer.processChunk(audioChunk);
  console.log(`Enhanced ${enhanced.length} samples`);
}

main().catch((err) => console.error(err.message));

import io.hecttor.sdk.*;

public class Minimal {
    public static void main(String[] args) {
        ASRSpeechEnhancerConfig config = ASRSpeechEnhancerConfig.builder("your_api_key_here")
            .chunkSizeMs(20)
            .sampleRate(16000)
            .model(new ASRSpeechEnhancerConfig.ModelConfig("your_model"))
            .build();

        try (ASRSpeechEnhancer enhancer = new ASRSpeechEnhancer()) {
            enhancer.initialize(config);
            int chunkSize = enhancer.getChunkSizeSamples();
            float[] audioChunk = new float[chunkSize];
            float[] enhanced = enhancer.processChunk(audioChunk);
            System.out.println("Enhanced " + enhanced.length + " samples");
        } catch (HecttorException e) {
            System.err.println("Error: " + e.getMessage());
            System.exit(1);
        }
    }
}

#include <hecttor/asr_speech_enhancer.hpp>
#include <iostream>
#include <vector>

int main() {
    try {
        hecttor::ASRSpeechEnhancerConfig config;
        config.apiKey = "your_api_key_here";
        config.chunkSizeMs = 20;
        config.sampleRate = 16000;
        config.modelConfig = hecttor::ModelConfig{"your_model"};

        hecttor::ASRSpeechEnhancer enhancer;
        enhancer.initialize(config);
        const size_t chunkSize = enhancer.getChunkSizeSamples();
        std::vector<float> audioChunk(chunkSize, 0.0f);
        std::vector<float> enhanced = enhancer.processChunk(audioChunk);
        std::cout << "Enhanced " << enhanced.size() << " samples\n";
    } catch (const std::exception& e) {
        std::cerr << "Error: " << e.what() << "\n";
        return 1;
    }
    return 0;
}

using System;
using Hecttor.SDK;

class Program
{
    static void Main()
    {
        var config = new ASRSpeechEnhancerConfig
        {
            ApiKey = "your_api_key_here",
            ChunkSizeMs = 20,
            SampleRate = 16000,
            Model = new ModelConfig { ModelName = "your_model" },
        };

        using var enhancer = new ASRSpeechEnhancer();
        enhancer.Initialize(config);
        int chunkSize = enhancer.ChunkSizeSamples;
        float[] audioChunk = new float[chunkSize];
        float[] enhanced = enhancer.ProcessChunk(audioChunk);
        Console.WriteLine($"Enhanced {enhanced.Length} samples");
    }
}

package main

import (
	"log"
	"os"

	hecttor "hecttor.ai/sdk"
)

func main() {
	enh, err := hecttor.NewASRSpeechEnhancer()
	if err != nil {
		log.Fatal(err)
	}
	defer enh.Close()

	if err := enh.Initialize(hecttor.ASRSpeechEnhancerConfig{
		APIKey:      os.Getenv("HECTTOR_API_KEY"),
		ChunkSizeMs: 20,
		SampleRate:  16000,
		Model:       hecttor.ModelConfig{ModelName: "your_model"},
	}); err != nil {
		log.Fatal(err)
	}

	chunkSize, err := enh.ChunkSizeSamples()
	if err != nil {
		log.Fatal(err)
	}
	audioChunk := make([]float32, chunkSize)
	enhanced, err := enh.ProcessChunk(audioChunk)
	if err != nil {
		log.Fatal(err)
	}
	log.Printf("Enhanced %d samples", len(enhanced))
}

Overriding the model's default blend weight

Each Orpheus model ships with a blend-weight default tuned for ASR performance: a solid starting point. Try other values against your evaluation to see whether a different blend lifts WER further on your audio.

config = ASRSpeechEnhancerConfig(
    api_key=os.environ["HECTTOR_API_KEY"],
    model_config=ModelConfig(model_name="your_model", enhancer_weight=0.8),
    chunk_size_ms=20,
    sample_rate=16000,
)

await enhancer.initialize({
  apiKey: process.env.HECTTOR_API_KEY,
  modelConfig: {
    modelName: 'your_model',
    enhancerWeight: 0.6,     // custom blend: 60% enhanced, 40% original
  },
  chunkSizeMs: 20,
  sampleRate: 16000,
});

ASRSpeechEnhancerConfig config = ASRSpeechEnhancerConfig.builder(apiKey)
    .model(new ASRSpeechEnhancerConfig.ModelConfig(
        "your_model",
        0.6f))                  // custom blend: 60% enhanced, 40% original
    .chunkSizeMs(20)
    .sampleRate(16000)
    .build();

hecttor::ASRSpeechEnhancerConfig config;
config.apiKey = apiKey;
config.modelConfig = hecttor::ModelConfig{
    "your_model",
    0.6f                     // custom blend: 60% enhanced, 40% original
};
config.chunkSizeMs = 20;
config.sampleRate = 16000;

var config = new ASRSpeechEnhancerConfig
{
    ApiKey = apiKey,
    Model = new ModelConfig
    {
        ModelName = "your_model",
        EnhancerWeight = 0.6f,   // custom blend: 60% enhanced, 40% original
    },
    ChunkSizeMs = 20,
    SampleRate = 16000,
};

enh, err := hecttor.NewASRSpeechEnhancer()
if err != nil {
	log.Fatal(err)
}
defer enh.Close()

if err := enh.Initialize(hecttor.ASRSpeechEnhancerConfig{
	APIKey: apiKey,
	Model: hecttor.ModelConfig{
		ModelName:      "your_model",
		EnhancerWeight: hecttor.Float32(0.6), // custom blend: 60% enhanced, 40% original
	},
	ChunkSizeMs: 20,
	SampleRate:  16000,
}); err != nil {
	log.Fatal(err)
}

Streaming pipeline shape

A typical real-time pipeline reads audio chunks from a source, runs them through Orpheus, and forwards the enhanced output to an ASR. The shape:

import os
import numpy as np
from hecttor_sdk import ASRSpeechEnhancer, ASRSpeechEnhancerConfig, ModelConfig

config = ASRSpeechEnhancerConfig(
    api_key=os.environ["HECTTOR_API_KEY"],
    model_config=ModelConfig(model_name="your_model"),
    chunk_size_ms=20,
    sample_rate=16000,
)

enhancer = ASRSpeechEnhancer()
ok, err = enhancer.initialize(config)
if not ok:
    raise RuntimeError(err)

chunk_size = enhancer.get_chunk_size_samples()

def stream_to_asr(audio_source, asr_client):
    """Read fixed-size chunks, enhance, forward to ASR."""
    for chunk in audio_source.iter_chunks(chunk_size):
        enhanced, err = enhancer.process_chunk(chunk.astype(np.float32))
        if enhanced is None:
            # Decide how to handle: skip, retry, or surface the error
            continue
        asr_client.send(enhanced)

const { ASRSpeechEnhancer } = require('hecttor_sdk');

// Pseudocode shape: replace audioSource/asrClient with your real adapters.
async function streamToAsr(apiKey, audioSource, asrClient, model = 'mist-1.0') {
  const enhancer = new ASRSpeechEnhancer();
  await enhancer.initialize({
    apiKey,
    chunkSizeMs: model === 'crest-2.0' ? 20 : 16,
    sampleRate: audioSource.sampleRate,
    modelConfig: { modelName: model },
  });

  const chunkSize = enhancer.getChunkSizeSamples();
  for await (const chunk of audioSource.iterChunks(chunkSize)) {
    try {
      const enhanced = await enhancer.processChunk(chunk);
      asrClient.send(enhanced);
    } catch (err) {
      // Decide how to handle: skip, retry, or surface the error
      console.error('processing error:', err.message);
    }
  }
}

import io.hecttor.sdk.*;

public class AsrStream {
    public static void streamToAsr(String apiKey,
                                   AudioSource audioSource,
                                   AsrClient asrClient,
                                   String model) throws Exception {
        ASRSpeechEnhancerConfig config = ASRSpeechEnhancerConfig.builder(apiKey)
            .chunkSizeMs("crest-2.0".equals(model) ? 20 : 16)
            .sampleRate(audioSource.sampleRate())
            .model(new ASRSpeechEnhancerConfig.ModelConfig(model))
            .build();

        try (ASRSpeechEnhancer enhancer = new ASRSpeechEnhancer()) {
            enhancer.initialize(config);
            int chunkSize = enhancer.getChunkSizeSamples();

            for (float[] chunk : audioSource.iterChunks(chunkSize)) {
                try {
                    float[] enhanced = enhancer.processChunk(chunk);
                    asrClient.send(enhanced);
                } catch (HecttorProcessingException e) {
                    // Decide how to handle: skip, retry, or surface the error
                    System.err.println("processing error: " + e.getMessage());
                }
            }
        }
    }
}

#include <hecttor/asr_speech_enhancer.hpp>

// Pseudocode shape: replace audioSource/asrClient with your real adapters.
void streamToAsr(const char* apiKey,
                 AudioSource& audioSource,
                 AsrClient& asrClient,
                 const std::string& model) {
    hecttor::ASRSpeechEnhancerConfig config;
    config.apiKey = apiKey;
    config.chunkSizeMs = (model == "crest-2.0") ? 20 : 16;
    config.sampleRate = audioSource.sampleRate();
    config.modelConfig = hecttor::ModelConfig{model};

    hecttor::ASRSpeechEnhancer enhancer;
    enhancer.initialize(config);

    const size_t chunkSize = enhancer.getChunkSizeSamples();
    std::vector<float> chunk(chunkSize);
    while (audioSource.nextChunk(chunk)) {
        try {
            std::vector<float> enhanced = enhancer.processChunk(chunk);
            asrClient.send(enhanced);
        } catch (const hecttor::ProcessingException& e) {
            // Decide how to handle: skip, retry, or surface the error
            std::cerr << "processing error: " << e.what() << "\n";
        }
    }
}

using System;
using Hecttor.SDK;

class AsrStream
{
    public static void StreamToAsr(string apiKey, IAudioSource source, IAsrClient asr, string model)
    {
        var config = new ASRSpeechEnhancerConfig
        {
            ApiKey = apiKey,
            ChunkSizeMs = model == "crest-2.0" ? 20 : 16,
            SampleRate = source.SampleRate,
            Model = new ModelConfig { ModelName = model },
        };

        using var enhancer = new ASRSpeechEnhancer();
        enhancer.Initialize(config);
        int chunkSize = enhancer.ChunkSizeSamples;

        foreach (var chunk in source.IterChunks(chunkSize))
        {
            try
            {
                float[] enhanced = enhancer.ProcessChunk(chunk);
                asr.Send(enhanced);
            }
            catch (HecttorProcessingException ex)
            {
                // Decide how to handle: skip, retry, or surface the error
                Console.Error.WriteLine($"processing error: {ex.Message}");
            }
        }
    }
}

package main

import (
	"log"

	hecttor "hecttor.ai/sdk"
)

// Pseudocode shape: replace AudioSource / AsrClient with your real adapters.
type AudioSource interface {
	SampleRate() int
	IterChunks(size int) <-chan []float32
}

type AsrClient interface {
	Send(samples []float32)
}

func streamToAsr(apiKey string, source AudioSource, asr AsrClient, model string) error {
	chunkSizeMs := 16
	if model == "crest-2.0" {
		chunkSizeMs = 20
	}

	enh, err := hecttor.NewASRSpeechEnhancer()
	if err != nil {
		return err
	}
	defer enh.Close()

	if err := enh.Initialize(hecttor.ASRSpeechEnhancerConfig{
		APIKey:      apiKey,
		ChunkSizeMs: chunkSizeMs,
		SampleRate:  source.SampleRate(),
		Model:       hecttor.ModelConfig{ModelName: model},
	}); err != nil {
		return err
	}

	chunkSize, err := enh.ChunkSizeSamples()
	if err != nil {
		return err
	}

	for chunk := range source.IterChunks(chunkSize) {
		enhanced, err := enh.ProcessChunk(chunk)
		if err != nil {
			// Decide how to handle: skip, retry, or surface the error
			log.Printf("processing error: %v", err)
			continue
		}
		asr.Send(enhanced)
	}
	return nil
}

Adapt the audio-source iteration and the ASR-send step to whatever your real audio source and ASR SDK provide.

Offline A/B evaluation

This is the shape for comparing WER before and after Orpheus on the same dataset. See Evaluations for full methodology.

import os
import numpy as np
from hecttor_sdk import ASRSpeechEnhancer, ASRSpeechEnhancerConfig, ModelConfig

config = ASRSpeechEnhancerConfig(
    api_key=os.environ["HECTTOR_API_KEY"],
    model_config=ModelConfig(model_name="your_model"),
    chunk_size_ms=20,
    sample_rate=16000,
)

enhancer = ASRSpeechEnhancer()
ok, err = enhancer.initialize(config)
if not ok:
    raise RuntimeError(err)

chunk_size = enhancer.get_chunk_size_samples()

def enhance_full_clip(samples_float32: np.ndarray) -> np.ndarray:
    """Run a full clip through Orpheus, chunk by chunk."""
    out = []
    for start in range(0, len(samples_float32) - chunk_size + 1, chunk_size):
        chunk = samples_float32[start : start + chunk_size]
        enhanced, err = enhancer.process_chunk(chunk)
        if enhanced is None:
            raise RuntimeError(f"Enhancement failed at sample {start}: {err}")
        out.append(enhanced)
    return np.concatenate(out)

# For each clip in your evaluation dataset:
#   baseline_transcript = your_asr.transcribe(original)
#   enhanced_transcript = your_asr.transcribe(enhance_full_clip(original))
#   compute WER on each against the ground-truth reference

const { ASRSpeechEnhancer } = require('hecttor_sdk');

async function main() {
  const enhancer = new ASRSpeechEnhancer();
  await enhancer.initialize({
    apiKey: process.env.HECTTOR_API_KEY,
    chunkSizeMs: 20,
    sampleRate: 16000,
    modelConfig: { modelName: 'your_model' },
  });

  const chunkSize = enhancer.getChunkSizeSamples();

  // Run a full clip through Orpheus, chunk by chunk.
  async function enhanceFullClip(samples) {
    const parts = [];
    for (let start = 0; start + chunkSize <= samples.length; start += chunkSize) {
      const chunk = samples.subarray(start, start + chunkSize);
      try {
        parts.push(await enhancer.processChunk(chunk));
      } catch (err) {
        throw new Error(`Enhancement failed at sample ${start}: ${err.message}`);
      }
    }
    const totalLen = parts.reduce((s, a) => s + a.length, 0);
    const result = new Float32Array(totalLen);
    let pos = 0;
    for (const a of parts) { result.set(a, pos); pos += a.length; }
    return result;
  }

  // For each clip in your evaluation dataset:
  //   const baseline = await yourAsr.transcribe(original);
  //   const enhanced = await yourAsr.transcribe(await enhanceFullClip(original));
  //   compute WER on each against the ground-truth reference
}

main().catch((err) => console.error(err.message));

import io.hecttor.sdk.*;
import java.util.ArrayList;
import java.util.List;

public class OfflineEvaluation {
    public static void main(String[] args) throws Exception {
        ASRSpeechEnhancerConfig config = ASRSpeechEnhancerConfig.builder(System.getenv("HECTTOR_API_KEY"))
            .chunkSizeMs(20)
            .sampleRate(16000)
            .model(new ASRSpeechEnhancerConfig.ModelConfig("your_model"))
            .build();

        try (ASRSpeechEnhancer enhancer = new ASRSpeechEnhancer()) {
            enhancer.initialize(config);
            int chunkSize = enhancer.getChunkSizeSamples();

            // For each clip in your evaluation dataset:
            //   String baseline = yourAsr.transcribe(samples);
            //   String enhanced = yourAsr.transcribe(enhanceFullClip(enhancer, samples, chunkSize));
            //   compute WER on each against the ground-truth reference
        }
    }

    // Run a full clip through Orpheus, chunk by chunk.
    static float[] enhanceFullClip(ASRSpeechEnhancer enhancer, float[] samples, int chunkSize) {
        List<float[]> parts = new ArrayList<>();
        int total = 0;
        for (int start = 0; start + chunkSize <= samples.length; start += chunkSize) {
            float[] chunk = new float[chunkSize];
            System.arraycopy(samples, start, chunk, 0, chunkSize);
            try {
                float[] enhanced = enhancer.processChunk(chunk);
                parts.add(enhanced);
                total += enhanced.length;
            } catch (HecttorProcessingException e) {
                throw new RuntimeException(
                    "Enhancement failed at sample " + start + ": " + e.getMessage(), e);
            }
        }
        float[] result = new float[total];
        int pos = 0;
        for (float[] a : parts) { System.arraycopy(a, 0, result, pos, a.length); pos += a.length; }
        return result;
    }
}

#include <hecttor/asr_speech_enhancer.hpp>

#include <cstdlib>
#include <stdexcept>
#include <string>
#include <vector>

// Run a full clip through Orpheus, chunk by chunk.
std::vector<float> enhanceFullClip(hecttor::ASRSpeechEnhancer& enhancer,
                                   const std::vector<float>& samples,
                                   size_t chunkSize) {
    std::vector<float> out;
    out.reserve(samples.size());
    for (size_t start = 0; start + chunkSize <= samples.size(); start += chunkSize) {
        std::vector<float> chunk(samples.begin() + start,
                                 samples.begin() + start + chunkSize);
        try {
            std::vector<float> enhanced = enhancer.processChunk(chunk);
            out.insert(out.end(), enhanced.begin(), enhanced.end());
        } catch (const hecttor::ProcessingException& e) {
            throw std::runtime_error(
                "Enhancement failed at sample " + std::to_string(start) + ": " + e.what());
        }
    }
    return out;
}

int main() {
    hecttor::ASRSpeechEnhancerConfig config;
    config.apiKey = std::getenv("HECTTOR_API_KEY");
    config.chunkSizeMs = 20;
    config.sampleRate = 16000;
    config.modelConfig = hecttor::ModelConfig{"your_model"};

    hecttor::ASRSpeechEnhancer enhancer;
    enhancer.initialize(config);
    const size_t chunkSize = enhancer.getChunkSizeSamples();

    // For each clip in your evaluation dataset:
    //   auto baseline = yourAsr.transcribe(samples);
    //   auto enhanced = yourAsr.transcribe(enhanceFullClip(enhancer, samples, chunkSize));
    //   compute WER on each against the ground-truth reference

    return 0;
}

using System;
using System.Collections.Generic;
using Hecttor.SDK;

class OfflineEvaluation
{
    // Run a full clip through Orpheus, chunk by chunk.
    static float[] EnhanceFullClip(ASRSpeechEnhancer enhancer, float[] samples, int chunkSize)
    {
        var parts = new List<float[]>();
        int total = 0;
        for (int start = 0; start + chunkSize <= samples.Length; start += chunkSize)
        {
            float[] chunk = new float[chunkSize];
            Array.Copy(samples, start, chunk, 0, chunkSize);
            try
            {
                float[] enhanced = enhancer.ProcessChunk(chunk);
                parts.Add(enhanced);
                total += enhanced.Length;
            }
            catch (HecttorProcessingException ex)
            {
                throw new InvalidOperationException(
                    $"Enhancement failed at sample {start}: {ex.Message}", ex);
            }
        }

        float[] result = new float[total];
        int pos = 0;
        foreach (var a in parts) { Array.Copy(a, 0, result, pos, a.Length); pos += a.Length; }
        return result;
    }

    static void Main()
    {
        var config = new ASRSpeechEnhancerConfig
        {
            ApiKey = Environment.GetEnvironmentVariable("HECTTOR_API_KEY"),
            ChunkSizeMs = 20,
            SampleRate = 16000,
            Model = new ModelConfig { ModelName = "your_model" },
        };

        using var enhancer = new ASRSpeechEnhancer();
        enhancer.Initialize(config);
        int chunkSize = enhancer.ChunkSizeSamples;

        // For each clip in your evaluation dataset:
        //   var baseline = yourAsr.Transcribe(samples);
        //   var enhanced = yourAsr.Transcribe(EnhanceFullClip(enhancer, samples, chunkSize));
        //   compute WER on each against the ground-truth reference
    }
}

package main

import (
	"fmt"
	"log"
	"os"

	hecttor "hecttor.ai/sdk"
)

// Run a full clip through Orpheus, chunk by chunk.
func enhanceFullClip(enh *hecttor.ASRSpeechEnhancer, samples []float32, chunkSize int) ([]float32, error) {
	out := make([]float32, 0, len(samples))
	for start := 0; start+chunkSize <= len(samples); start += chunkSize {
		chunk := samples[start : start+chunkSize]
		enhanced, err := enh.ProcessChunk(chunk)
		if err != nil {
			return nil, fmt.Errorf("enhancement failed at sample %d: %w", start, err)
		}
		out = append(out, enhanced...)
	}
	return out, nil
}

func main() {
	enh, err := hecttor.NewASRSpeechEnhancer()
	if err != nil {
		log.Fatal(err)
	}
	defer enh.Close()

	if err := enh.Initialize(hecttor.ASRSpeechEnhancerConfig{
		APIKey:      os.Getenv("HECTTOR_API_KEY"),
		ChunkSizeMs: 20,
		SampleRate:  16000,
		Model:       hecttor.ModelConfig{ModelName: "your_model"},
	}); err != nil {
		log.Fatal(err)
	}

	chunkSize, err := enh.ChunkSizeSamples()
	if err != nil {
		log.Fatal(err)
	}
	_ = chunkSize

	// For each clip in your evaluation dataset:
	//   baseline := yourAsr.Transcribe(samples)
	//   enhanced, _ := enhanceFullClip(enh, samples, chunkSize)
	//   transcript := yourAsr.Transcribe(enhanced)
	//   compute WER on each against the ground-truth reference
}

Initialize Orpheus once and reuse the enhancer for the entire evaluation. Re-initializing per clip is wasted work; initialization loads models and validates the key.

Examples

Minimal real-time enhancement

Overriding the model's default blend weight

Streaming pipeline shape

Offline A/B evaluation

On this page