snowboy

README

go-snowboy

The Go bindings for snowboy audio detection (https://github.com/Kitt-AI/snowboy) are generated using swig which creates a lot of extra types and uses calls with variable arguments. This makes writing integrations in golang difficult because the types aren't explicit. go-snowboy is intended to be a wrapper around the swig-generated Go code which will provide Go-style usage.

Docs

See https://godoc.org/github.com/brentnd/go-snowboy

Dependencies

• SWIG (v 3.0.12 recommended)

Go Packages

• github.com/Kitt-AI/snowboy/swig/Go

Example

Example hotword detection usage in example/detect.go. Example API hotword training usage in example/api.go.

Building

go build -o build/snowboy-detect example/detect.go
go build -o build/snowboy-api example/api.go
go build -o build/snowboy-listen example/listen.go

Running

usage: ./build/snowboy-detect <resource> <keyword.umdl> <audio file>
usage: ./build/snowboy-listen <resource> <keyword.umdl>

See Also

Makefile has some standard targets to do go build steps

Documentation

Overview

Package go-snowboy provides a Go-style wrapper for the swig-generate Go code from Kitt-AI/snowboy

Simple audio hotword detection:

det := snowboy.NewDetector("resources/common.res")
defer det.Close()
// ...
det.Handle(snowboy.NewHotword("resources/alexa.umdl", 0.5), alexaHandler)

det.HandleFunc(snowboy.NewHotword("resources/snowboy.umdl", 0.5), func(keyword string) {
	fmt.Println("detected 'snowboy' keyword")
})

var data io.Reader
// ...
log.Fatal(det.ReadAndDetect(data))

The Go bindings for snowboy audio detection (https://github.com/Kitt-AI/snowboy) are generated using swig which creates a lot of extra types and uses calls with variable arguments. This makes writing integrations in golang difficult because the types aren't explicit. go-snowboy is intended to be a wrapper around the swig-generated Go code which will provide Go-style usage.

Index

• Constants
• Variables
• type AgeGroup
• type Detector
  • func NewDetector(resourceFile string) Detector
  • func (d *Detector) ApplyFrontend(apply bool)
  • func (d *Detector) AudioFormat() (sampleRate, numChannels, bitsPerSample int)
  • func (d *Detector) Close() error
  • func (d *Detector) Detect(data []byte) error
  • func (d *Detector) Handle(hotword Hotword, handler Handler)
  • func (d *Detector) HandleFunc(hotword Hotword, handler func(string))
  • func (d *Detector) HandleSilence(threshold time.Duration, handler Handler)
  • func (d *Detector) HandleSilenceFunc(threshold time.Duration, handler func(string))
  • func (d *Detector) NumNotwords() int
  • func (d *Detector) ReadAndDetect(data io.Reader) error
  • func (d *Detector) Reset() bool
  • func (d *Detector) SetAudioGain(gain float32)
• type Gender
• type Handler
• type Hotword
  • func NewDefaultHotword(model string) Hotword
  • func NewHotword(model string, sensitivity float32) Hotword
• type Language
• type TrainRequest
  • func (t *TrainRequest) AddWave(filename string)
  • func (t *TrainRequest) Train() ([]byte, error)
• type VoiceSample

Constants

const (
	EndpointBase    = "https://snowboy.kitt.ai/api/"
	EndpointVersion = "v1"
	EndpointTrain   = EndpointBase + EndpointVersion + "/train"
	EndpointImprove = EndpointBase + EndpointVersion + "/improve"
)

const (
	AgeGroup0s     AgeGroup = "0_9"
	AgeGroup10s             = "10_19"
	AgeGroup20s             = "20_29"
	AgeGroup30s             = "30_39"
	AgeGroup40s             = "40_49"
	AgeGroup50s             = "50_59"
	AgeGroup60plus          = "60+"
)

const (
	LanguageArabic     Language = "ar"
	LanguageChinese             = "zh"
	LanguageDutch               = "nl"
	LanguageEnglish             = "en"
	LanguageFrench              = "fr"
	LanguageGerman              = "dt"
	LanguageHindi               = "hi"
	LanguageItalian             = "it"
	LanguageJapanese            = "jp"
	LanguageKorean              = "ko"
	LanguagePersian             = "fa"
	LanguagePolish              = "pl"
	LanguagePortuguese          = "pt"
	LanguageRussian             = "ru"
	LanguageSpanish             = "es"
	LanguageOther               = "ot"
)

Variables

var (
	NoHandler           = errors.New("No handler installed")
	SnowboyLibraryError = errors.New("snowboy library error")
)

Types

type AgeGroup

type AgeGroup string

type Detector

type Detector struct {
	ResourceFile string
	AudioGain    float32
	// contains filtered or unexported fields
}

Detector is holds the context and base impl for snowboy audio detection

func NewDetector

func NewDetector(resourceFile string) Detector

Creates a standard Detector from a resources file

Gives a default gain of 1.0

func (*Detector) ApplyFrontend

func (d *Detector) ApplyFrontend(apply bool)

Applies or removes frontend audio processing

func (*Detector) AudioFormat

func (d *Detector) AudioFormat() (sampleRate, numChannels, bitsPerSample int)

Fetch the format for the expected audio input

Returns sample rate, number of channels, and bit depth

func (*Detector) Close

func (d *Detector) Close() error

Close handles cleanup required by snowboy library

Clients must call Close on detectors after doing any detection Returns error if Detector was never used

func (*Detector) Detect

func (d *Detector) Detect(data []byte) error

Calls previously installed handlers if hotwords are detected in data

Does not chunk data because it is all available. Assumes entire length of data is filled and will only call one handler

func (*Detector) Handle

func (d *Detector) Handle(hotword Hotword, handler Handler)

Install a handler for the given hotword

func (*Detector) HandleFunc

func (d *Detector) HandleFunc(hotword Hotword, handler func(string))

Installs a handle for the given hotword based on the func argument instead of the Handler interface

func (*Detector) HandleSilence

func (d *Detector) HandleSilence(threshold time.Duration, handler Handler)

Install a handler for when silence is detected

threshold (time.Duration) determined how long silence can occur before callback is called

func (*Detector) HandleSilenceFunc

func (d *Detector) HandleSilenceFunc(threshold time.Duration, handler func(string))

Installs a handle for when silence is detected based on the func argument instead of the Handler interface

threshold (time.Duration) determined how long silence can occur before callback is called

func (*Detector) NumNotwords

func (d *Detector) NumNotwords() int

Returns the number of loaded hotwords

func (*Detector) ReadAndDetect

func (d *Detector) ReadAndDetect(data io.Reader) error

Reads from data and calls previously installed handlers when detection occurs

Blocks while reading from data in chunks of 2048 bytes. Data examples include file, pipe from Stdout of exec, response from http call, any reader really.

*Note, be careful with using byte.Buffer for data. When io.EOF is received from a read call on data, ReadAndDetect will exit

func (*Detector) Reset

func (d *Detector) Reset() bool

Resets the detection. The underlying snowboy object handles voice activity detection (VAD) internally, but if you are using an external VAD, you should call Reset() whenever you see the segment end.

func (*Detector) SetAudioGain

func (d *Detector) SetAudioGain(gain float32)

Applies a fixed gain to the input audio. In case you have a very weak microphone, you can use this function to boost input audio level.

type Gender

type Gender string

const (
	GenderMale   Gender = "M"
	GenderFemale        = "F"
)

type Handler

type Handler interface {
	Detected(string)
}

A Handler is used to handle when keywords are detected

Detected will be call with the keyword string

type Hotword

type Hotword struct {
	Model       string
	Sensitivity float32
	Name        string
}

A Hotword represents a model filename and sensitivity for a snowboy detectable word

Model is the filename for the .umdl file

Sensitivity is the sensitivity of this specific hotword

Name is what will be used in calls to Handler.Detected(string)

func NewDefaultHotword

func NewDefaultHotword(model string) Hotword

Creates a hotword from model only, parsing the hotward name from the model filename and using a sensitivity of 0.5

func NewHotword

func NewHotword(model string, sensitivity float32) Hotword

Creates a hotword from model and sensitivity only, parsing the hotward name from the model filename

type Language

type Language string

type TrainRequest

type TrainRequest struct {
	VoiceSamples []VoiceSample `json:"voice_samples"`
	Token        string        `json:"token"`
	Name         string        `json:"name"`
	Language     Language      `json:"language"`
	AgeGroup     AgeGroup      `json:"age_group"`
	Gender       Gender        `json:"gender"`
	Microphone   string        `json:"microphone"`
}

func (*TrainRequest) AddWave

func (t *TrainRequest) AddWave(filename string)

func (*TrainRequest) Train

func (t *TrainRequest) Train() ([]byte, error)

type VoiceSample

type VoiceSample struct {
	Wave string `json:"wave"`
}