houndify

README

Houndify SDK for Go

houndify-sdk-go is the official Houndify SDK for the Go programming language.

The SDK allows you to make voice and text queries to the Houndify API. The SDK comes with a fully functional example app that demonstrates usage and the various SDK features. The SDK has no third party dependencies.

Requirements

• Go v1.8+
• Houndify account available from Houndify.com

Installing

To use the SDK and/or example app, you will need a client ID and client key. You can get those after creating a Houndify account and registering a client.

Once you have set your $GOPATH, you can use both the Go Houndify SDK and example app.

go get github.com/soundhound/houndify-sdk-go

The example app will be compiled and available at $GOPATH/bin/houndify-sdk-go and the SDK will be ready to import and use.

Example App

example.go provides a working example using the SDK.

The example app features three modes of interacting with the Houndify API:

1. Voice
2. Text
3. Stdin Interactive Text

To run the voice search:

houndify-sdk-go --id YOUR_CLIENT_ID --key YOUR_CLIENT_KEY --voice ./test_audio/whattimeisitindenver.wav

To run a text search:

houndify-sdk-go --id YOUR_CLIENT_ID --key YOUR_CLIENT_KEY --text "tell me a joke"

To run an interactive text search:

houndify-sdk-go --id YOUR_CLIENT_ID --key YOUR_CLIENT_KEY --stdin

You will then be prompted to type a query.

After Houndify replies with a response, you can follow up with additional text queries. Houndify will keep track of the conversation history, and interpret new queries in the context of previous ones.

An example set of queries:

• "what is two plus six"
• "minus 4"
• "what is the square root of that"

Instead of using the --id and --key flags, you may set the environment variables HOUNDIFY_CLIENT_ID and HOUNDIFY_CLIENT_KEY.

Using the SDK

To use the SDK, you must import the package

import (
    houndify "github.com/soundhound/houndify-sdk-go/houndify"
)

Create a new client

client := houndify.Client{
    ClientID:  "YOUR_CLIENT_ID",
    ClientKey: "YOUR_CLIENT_KEY",
}

For a voice search, create a VoiceRequest and channel for partial transcripts. The audio to be streamed must already be the correct encoding that the server requires. See the Houndify Docs for details. There are example audio files to test with in test_audio.

req := houndify.VoiceRequest{
    AudioStream:       bytes.NewReader(audioDataByteArray),
    UserID:            "appUser123",
    RequestID:         "uniqueRequest456",
    RequestInfoFields: make(map[string]interface{}),
}

//listen for partial transcripts while audio is streaming
partialTranscripts := make(chan houndify.PartialTranscript)
go func() {
    for partial := range partialTranscripts {
        fmt.Println(partial.Message)
    }
}()

serverResponse, err := client.VoiceSearch(req, partialTranscripts)

For a text search, create a TextRequest

req := houndify.TextRequest{
    Query:             "what time is it in paris",
    UserID:            "appUser123",
    RequestID:         "uniqueRequest456",
    RequestInfoFields: make(map[string]interface{}),
}

serverResponse, err := client.TextSearch(req)

Conversation State

Houndified domains can use context to enable a conversational user interaction. For example, users can say "show me coffee shops near me", "which ones have wifi?", "sort by rating", "navigate to the first one". You can enable, disable, clear, set and get the client's conversation state with the following houndify.Client methods.

client.EnableConversationState()

client.DisableConversationState()

client.ClearConversationState()

currentState := client.GetConversationState()

client.SetConversationState(newState)

Contributing

There are multiple ways to contribute to the SDK.

If you found a bug or have a feature request, please open an Issue.

If you would like to make a code contribution, please sign the CLA, and make a Pull Request with your changes.

For account issues, security issues, or if you are unable to post publicly, please contact us directly.

License

The Houndify SDK for Go is distributed under the MIT License. See the LICENSE file for more information.

Documentation

Index

• Constants
• func ParseWrittenResponse(serverResponseJSON string) (string, error)
• type Client
  • func (c *Client) ClearConversationState()
  • func (c *Client) DisableConversationState()
  • func (c *Client) EnableConversationState()
  • func (c *Client) GetConversationState() interface{}
  • func (c *Client) SetConversationState(newState interface{})
  • func (c *Client) TextSearch(textReq TextRequest) (string, error)
  • func (c *Client) VoiceSearch(voiceReq VoiceRequest, partialTranscriptChan chan PartialTranscript) (string, error)
• type PartialTranscript
• type TextRequest
• type VoiceRequest

Constants

const SDKUserAgent = "Go Houndify SDK"

Default user agent set by the SDK

Functions

func ParseWrittenResponse

func ParseWrittenResponse(serverResponseJSON string) (string, error)

ParseWrittenResponse will take final server response JSON (as a string) and parse out the human readable text to be displayed or spoken the end user. If the string is invalid JSON, the server had an error, or there was nothing to reply with, an error is returned.

Types

type Client

type Client struct {
	// The ClientID comes from the Houndify site.
	ClientID string
	// The ClientKey comes from the Houndify site.
	// Keep the key secret.
	ClientKey string

	// If Verbose is true, all data sent from the server is printed to stdout, unformatted and unparsed.
	// This includes partial transcripts, errors, HTTP headers details (status code, headers, etc.), and final response JSON.
	Verbose bool
	// contains filtered or unexported fields
}

A Client holds the configuration and state, which is used for sending all outgoing Houndify requests and appropriately saving their responses.

func (*Client) ClearConversationState

func (c *Client) ClearConversationState()

ClearConversationState removes, or "forgets", the current conversation state

func (*Client) DisableConversationState

func (c *Client) DisableConversationState()

DisableConversationState disables conversation state for future queries

func (*Client) EnableConversationState

func (c *Client) EnableConversationState()

EnableConversationState enables conversation state for future queries

func (*Client) GetConversationState

func (c *Client) GetConversationState() interface{}

GetConversationState returns the current conversation state, useful for saving

func (*Client) SetConversationState

func (c *Client) SetConversationState(newState interface{})

SetConversationState sets the conversation state, useful for resuming from a saved point

func (*Client) TextSearch

func (c *Client) TextSearch(textReq TextRequest) (string, error)

TextSearch sends a text request and returns the body of the Hound server response.

An error is returned if there is a failure to create the request, failure to connect, failure to parse the response, or failure to update the conversation state (if applicable).

func (*Client) VoiceSearch

func (c *Client) VoiceSearch(voiceReq VoiceRequest, partialTranscriptChan chan PartialTranscript) (string, error)

VoiceSearch sends an audio request and returns the body of the Hound server response.

The partialTranscriptChan parameter allows the caller to receive for PartialTranscripts while the Hound server is listening to the voice search. If partial transcripts are not needed, create a throwaway channel that listens and discards all the PartialTranscripts sent.

An error is returned if there is a failure to create the request, failure to connect, failure to parse the response, or failure to update the conversation state (if applicable).

type PartialTranscript

type PartialTranscript struct {
	// The text of the partial transcript
	Message string
	// Length of audio this partial transcript applies to
	Duration time.Duration
	// If this is the last partial transcript
	Done bool
}

type TextRequest

type TextRequest struct {
	// The text query, e.g. "what time is it in london"
	Query             string
	UserID            string
	RequestID         string
	RequestInfoFields map[string]interface{}
}

A TextRequest holds all the information needed to make a Houndify request. Create one of these per request to send and use a Client to send it.

type VoiceRequest

type VoiceRequest struct {
	// Stream of audio in bytes. It must already be in correct encoding.
	// See the Houndify docs for details.
	AudioStream       io.Reader
	UserID            string
	RequestID         string
	RequestInfoFields map[string]interface{}
}

A VoiceRequest holds all the information needed to make a Houndify request. Create one of these per request to send and use a Client to send it.