freesound

README

freesound

golang client and command-line tool for the freesound API

Status

Usage

$ go get github.com/briansorahan/freesound

import (
       "github.com/briansorahan/freesound"
)

Documentation

Overview

Package freesound provides a client for the freesound.org API v2.

Index

• Constants
• Variables
• type APIError
• type AccessTokenResponse
• type Avatar
• type Client
  • func New(id, secret string) (*Client, error)
  • func (c *Client) CodeURL() string
  • func (c *Client) Do(req *http.Request) (*http.Response, error)
  • func (c *Client) GetAccessToken(authCode string) (AccessTokenResponse, error)
  • func (c *Client) GetUser(name string) (*User, error)
  • func (c *Client) PendingUploads() (PendingUploadsResponse, error)
  • func (c *Client) RefreshAccessToken(refreshToken string) (AccessTokenResponse, error)
  • func (c *Client) SetAccessToken(accessToken string)
  • func (c *Client) Upload(pathAudio string, upload Upload) (*http.Response, error)
• type Images
• type PendingModeration
• type PendingUploadsResponse
• type Sound
• type Time
  • func (t Time) MarshalJSON() ([]byte, error)
  • func (t *Time) UnmarshalJSON(bs []byte) error
• type Upload
  • func (upload Upload) Validate() error
  • func (upload Upload) WriteFields(w *multipart.Writer) error
• type User

Constants

const (
	GrantTypeAuthCode     = "authorization_code"
	GrantTypeRefreshToken = "refresh_token"
)

Grant types supported by freesound oauth.

const (
	VerbosityOff = iota
	VerbosityOn
)

Verbosity levels.

const (
	// BaseURL is the base URL for the freesound API v2.
	BaseURL = "http://www.freesound.org/apiv2"
)

Variables

var (
	// ErrMissingToken is returned whenever you call a method
	// that requires an access token before you call
	// SetAccessToken with a valid access token.
	ErrMissingToken = errors.New("missing access token")
)

Types

type APIError

type APIError struct {
	StatusCode  int    `json:"status_code,omitempty"`
	Explanation string `json:"explanation,omitempty"`
	Type        string `json:"type,omitempty"`
	Error       bool   `json:"error,omitempty"`
}

APIError represents an error that comes back from the freesound API.

type AccessTokenResponse

type AccessTokenResponse struct {
	AccessToken  string `json:"access_token"`
	Scope        string `json:"scope"`
	ExpiresIn    int64  `json:"expires_in"` // seconds
	RefreshToken string `json:"refresh_token"`
}

AccessTokenResponse is the structure of a response from the /apiv2/oauth2/access_token/ endpoint.

type Avatar

type Avatar struct {
	Small  string `json:"small"`
	Medium string `json:"medium"`
	Large  string `json:"large"`
}

Avatar contains the links for a user's avatar.

type Client

type Client struct {
	ID        string `json:"id"`
	Secret    string `json:"secret"`
	Verbosity int    `json:"verbosity"`
	// contains filtered or unexported fields
}

Client represents a freesound API client.

func New

func New(id, secret string) (*Client, error)

New creates a new freesound API client.

func (*Client) CodeURL

func (c *Client) CodeURL() string

CodeURL returns a url used to create an authorization code.

func (*Client) Do

func (c *Client) Do(req *http.Request) (*http.Response, error)

Do performs an http request. Callers are expected to close the response body when the returned error is nil.

func (*Client) GetAccessToken

func (c *Client) GetAccessToken(authCode string) (AccessTokenResponse, error)

GetAccessToken gets an oauth access token with the provided auth code. Client code is responsible for closing the response body.

func (*Client) GetUser

func (c *Client) GetUser(name string) (*User, error)

GetUser gets a user profile.

func (*Client) PendingUploads

func (c *Client) PendingUploads() (PendingUploadsResponse, error)

PendingUploads returns your pending uploads.

func (*Client) RefreshAccessToken

func (c *Client) RefreshAccessToken(refreshToken string) (AccessTokenResponse, error)

RefreshAccessToken refreshes an access token that has expired. Access tokens only last 24 hours, so this is a common operation.

func (*Client) SetAccessToken

func (c *Client) SetAccessToken(accessToken string)

SetAccessToken sets the access token to be used by the client.

func (*Client) Upload

func (c *Client) Upload(pathAudio string, upload Upload) (*http.Response, error)

Upload uploads the sound located at pathAudio. This requires an oauth access token.

type Images

type Images struct {
	WaveformL string `json:"waveform_l"`
	WaveformM string `json:"waveform_m"`
	SpectralL string `json:"spectral_l"`
	SpectralM string `json:"spectral_m"`
}

Images contains links to sound images.

type PendingModeration

type PendingModeration struct {
	Description string   `json:"description"`
	License     string   `json:"license"`
	Tags        []string `json:"tags"`
	Created     Time     `json:"created"`
	Images      Images   `json:"images"`
	ID          int      `json:"id"`
	Name        string   `json:"name"`
}

PendingModeration represents an uploaded sound that is pending moderation.

type PendingUploadsResponse

type PendingUploadsResponse struct {
	PendingDescription []string            `json:"pending_description"`
	PendingModeration  []PendingModeration `json:"pending_moderation"`
}

PendingUploadsResponse represents a response to /sounds/pending_uploads/

type Sound

type Sound struct {
	ID          int      `json:"id"`
	URL         string   `json:"url"`
	Name        string   `json:"name"`
	Tags        []string `json:"tags"`
	Description string   `json:"description"`
	Geotag      string   `json:"geotag"` // TODO: split into geo.Point
	Created     string   `json:"created"`
	License     string   `json:"license"`
	Type        string   `json:"type"`
	Channels    int      `json:"channels"`
	Filesize    int      `json:"filesize"` // Size of the file in bytes.
	Bitrate     int      `json:"bitrate"`
	Bitdepth    int      `json:"bitdepth"`
	Duration    int      `json:"duration"`
}

Sound represents a sound instance. See https://www.freesound.org/docs/api/resources_apiv2.html#sound-instance

type Time

type Time struct {
	time.Time
}

Time is a utility type for marshalling and unmarshalling timestamps. Timestamps in the freesound API don't have a 'Z' at then end, so we can not use the std library's time.Time.

func (Time) MarshalJSON

func (t Time) MarshalJSON() ([]byte, error)

MarshalJSON marshals a Time to JSON.

func (*Time) UnmarshalJSON

func (t *Time) UnmarshalJSON(bs []byte) error

UnmarshalJSON unmarshals a Time from JSON.

type Upload

type Upload struct {
	Name        string
	Tags        string
	Description string
	License     string
	Pack        string
	Geotag      string
}

Upload contains optional params for sound upload.

func (Upload) Validate

func (upload Upload) Validate() error

Validate validates the upload data. This just checks that if any one of tags, description, or license is provided then they all have been provided.

func (Upload) WriteFields

func (upload Upload) WriteFields(w *multipart.Writer) error

WriteFields writes upload fields to a multipart writer.

type User

type User struct {
	URL                string `json:"url,omitempty"`
	Name               string `json:"username,omitempty"`
	About              string `json:"about,omitempty"`
	Ref                string `json:"ref,omitempty"`
	HomePage           string `json:"home_page,omitempty"`
	Avatar             Avatar `json:"avatar,omitempty"`
	Joined             Time   `json:"date_joined,omitempty"`
	Sounds             string `json:"sounds,omitempty"`
	Packs              string `json:"packs,omitempty"`
	NumSounds          int    `json:"num_sounds"`
	NumPacks           int    `json:"num_packs"`
	NumComments        int    `json:"num_comments"`
	BookmarkCategories string `json:"bookmark_categories,omitempty"`
}

User represents a user of the freesound API.