houndify

package module
v0.3.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 26, 2022 License: MIT Imports: 18 Imported by: 10

README

Houndify SDK for Go Build Status GoDoc

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

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 houndify package:

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

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

View Source 
const SDKUserAgent = "Go Houndify SDK"

Default user agent set by the SDK

Variables

This section is empty.

Functions

func BuildRequest added in v0.3.1 

func BuildRequest(houndReq requestable, c Client) (*http.Request, error)

Take a generic requestable interface and create a http.Request from it using the built Client.

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
	HttpClient        *http.Client
	RequestInfoInBody 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
	SafeToStopAudio *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{}
	URL               string
	// contains filtered or unexported fields
}

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.

func (*TextRequest) AuthInfo added in v0.3.1 

func (r *TextRequest) AuthInfo(c Client) (authInfo, error)

func (*TextRequest) GetRequestInfo added in v0.3.1 

func (r *TextRequest) GetRequestInfo() map[string]interface{}

func (*TextRequest) Headers added in v0.3.4 

func (r *TextRequest) Headers(headers map[string]string)

func (*TextRequest) NewRequest added in v0.3.1 

func (r *TextRequest) NewRequest() (*http.Request, error)

func (*TextRequest) RequestInfo added in v0.3.1 

func (r *TextRequest) RequestInfo(c Client, reqInfo requestInfo) (requestInfo, error)

func (*TextRequest) WithContext added in v0.3.4 

func (r *TextRequest) WithContext(ctx context.Context)

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{}
	URL               string
	// contains filtered or unexported fields
}

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.

func (*VoiceRequest) AuthInfo added in v0.3.1 

func (r *VoiceRequest) AuthInfo(c Client) (authInfo, error)

func (*VoiceRequest) GetRequestInfo added in v0.3.1 

func (r *VoiceRequest) GetRequestInfo() map[string]interface{}

func (*VoiceRequest) Headers added in v0.3.4 

func (r *VoiceRequest) Headers(headers map[string]string)

func (*VoiceRequest) NewRequest added in v0.3.1 

func (r *VoiceRequest) NewRequest() (*http.Request, error)

func (*VoiceRequest) RequestInfo added in v0.3.1 

func (r *VoiceRequest) RequestInfo(c Client, reqInfo requestInfo) (requestInfo, error)

func (*VoiceRequest) WithContext added in v0.3.4 

func (r *VoiceRequest) WithContext(ctx context.Context)

Source Files

View all Source files

Directories

Path Synopsis
houndify module

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.