toniebox

README

Toniebox API - Go

A Go port of maximilianvoss/toniebox-api

A Go library for interacting with the Toniebox Cloud API. Control your Creative-Tonies, upload audio files, manage chapters, and more - all from your Go applications.

What is Toniebox?

The Toniebox is a popular audio player designed for children. It uses figurines called "Tonies" that play stories, songs, and other audio content. Creative-Tonies are special figurines that allow you to upload your own audio content.

Features

• 🔐 Authentication - Secure login with your Toniebox account credentials
• 👤 User Management - Retrieve your personal account information
• 🏠 Household Access - List and manage multiple households
• 🎭 Creative-Tonie Control - Access and control all your Creative-Tonies
• 📤 File Upload - Upload audio files to your Creative-Tonies
• 📝 Chapter Management - Add, remove, and organize chapters
• 🔄 Real-time Updates - Refresh to get the latest state from the cloud
• 🌐 Proxy Support - Optional proxy configuration for network environments

Installation

go get github.com/mikeboe/toniebox-api-go

Quick Start

package main

import (
    "fmt"
    "log"
    
    toniebox "github.com/mikeboe/toniebox-api-go"
)

func main() {
    // Create a new client
    client := toniebox.NewClient()
    
    // Login
    if err := client.Login("user@example.com", "password"); err != nil {
        log.Fatal(err)
    }
    
    // Get your households
    households, err := client.GetHouseholds()
    if err != nil {
        log.Fatal(err)
    }
    
    // Get Creative-Tonies
    tonies, err := client.GetCreativeTonies(&households[0])
    if err != nil {
        log.Fatal(err)
    }
    
    // Work with a Tonie
    tonie := &tonies[0]
    fmt.Printf("Tonie: %s has %d chapters\n", tonie.Name, tonie.ChaptersPresent)
}

Usage Examples

Authentication

// Create a client
client := toniebox.NewClient()

// Or with proxy support
client, err := toniebox.NewClientWithProxy("http://proxy.example.com:8080")

// Login
err := client.Login("user@example.com", "password")

Get User Information

me, err := client.GetMe()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User: %s %s\n", me.FirstName, me.LastName)

List Households and Creative-Tonies

// Get all households
households, err := client.GetHouseholds()
if err != nil {
    log.Fatal(err)
}

// Get Creative-Tonies from a household
tonies, err := client.GetCreativeTonies(&households[0])
if err != nil {
    log.Fatal(err)
}

for _, tonie := range tonies {
    fmt.Printf("Tonie: %s (Chapters: %d)\n", tonie.Name, tonie.ChaptersPresent)
}

Upload an Audio File

tonie := &tonies[0]

// Upload a file
err := tonie.UploadFile("My Story", "/path/to/audio.mp3")
if err != nil {
    log.Fatal(err)
}

// Commit changes
err = tonie.Commit()
if err != nil {
    log.Fatal(err)
}

Manage Chapters

// Find a chapter by title
chapter := tonie.FindChapterByTitle("Old Story")
if chapter != nil {
    // Delete the chapter
    tonie.DeleteChapter(chapter)
    
    // Commit changes
    tonie.Commit()
}

Rename a Creative-Tonie

tonie.Name = "New Name"
err := tonie.Commit()
if err != nil {
    log.Fatal(err)
}

Refresh State

// Refresh to get the latest state from the cloud
err := tonie.Refresh()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Current chapters: %d\n", tonie.ChaptersPresent)

Running the Example

A complete example application is included in the examples directory:

# Set your credentials
export TONIEBOX_USERNAME="your-email@example.com"
export TONIEBOX_PASSWORD="your-password"

# Run the example
cd examples
go run main.go

API Documentation

For detailed API documentation, see the GoDoc.

Main Types

• Client - Main API client for authentication and accessing resources
• CreativeTonie - Represents a Creative-Tonie figurine with methods for managing content
• Household - Represents a household/family group
• Chapter - Represents an audio chapter/track on a Creative-Tonie
• Me - User account information

Main Methods

Client Methods

• NewClient() - Create a new API client
• NewClientWithProxy(proxyURL) - Create a client with proxy support
• Login(username, password) - Authenticate with your Toniebox account
• GetMe() - Get your user information
• GetHouseholds() - List all households you belong to
• GetCreativeTonies(household) - List Creative-Tonies in a household

CreativeTonie Methods

• UploadFile(title, filePath) - Upload an audio file
• Commit() - Save changes to the cloud
• Refresh() - Reload the latest state
• FindChapterByTitle(title) - Find a chapter by its title
• DeleteChapter(chapter) - Remove a chapter

Requirements

• Go 1.21 or higher
• Active Toniebox account
• Internet connection

Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

License

This project is licensed under the MIT License - see the LICENSE file for details.

Credits

This is a Go port of the original Java implementation by Maximilian Voss.

Disclaimer

This is an unofficial library and is not affiliated with, endorsed by, or connected to Boxine GmbH or the Toniebox brand. Use at your own risk.

Documentation

Index

• type AmazonBean
• type Chapter
• type Client
  • func NewClient() *Client
  • func NewClientWithProxy(proxyURL string) (*Client, error)
  • func (c *Client) GetCreativeTonies(household *Household) ([]CreativeTonie, error)
  • func (c *Client) GetHouseholds() ([]Household, error)
  • func (c *Client) GetMe() (*Me, error)
  • func (c *Client) Login(username, password string) (*JWTToken, error)
  • func (c *Client) SetToken(token *JWTToken)
• type CreativeTonie
  • func (ct *CreativeTonie) Commit() error
  • func (ct *CreativeTonie) DeleteChapter(chapter *Chapter)
  • func (ct *CreativeTonie) FindChapterByTitle(title string) *Chapter
  • func (ct *CreativeTonie) Refresh() error
  • func (ct *CreativeTonie) UploadFile(title, filePath string) error
• type FieldsBean
• type Household
• type JWTToken
• type Login
• type Me
• type RequestBean

Types

type AmazonBean

type AmazonBean struct {
	FileID  string      `json:"fileId"`
	Request RequestBean `json:"request"`
}

AmazonBean represents the Amazon S3 upload response

type Chapter

type Chapter struct {
	ID          string  `json:"id"`
	File        string  `json:"file"`
	Title       string  `json:"title"`
	Seconds     float64 `json:"seconds"`
	Transcoding bool    `json:"transcoding"`
}

Chapter represents a chapter/track on a Creative-Tonie

type Client

type Client struct {
	// contains filtered or unexported fields
}

Client is the main interface for interacting with the Toniebox API. It provides methods for authentication and accessing Toniebox resources.

func NewClient

func NewClient() *Client

NewClient creates a new Toniebox API client with default settings.

Example:

client := toniebox.NewClient()
err := client.Login("user@example.com", "password")

func NewClientWithProxy

func NewClientWithProxy(proxyURL string) (*Client, error)

NewClientWithProxy creates a new Toniebox API client with a proxy. The proxyURL should be in the format "http://host:port" or "https://host:port".

Example:

client, err := toniebox.NewClientWithProxy("http://proxy.example.com:8080")

func (*Client) GetCreativeTonies

func (c *Client) GetCreativeTonies(household *Household) ([]CreativeTonie, error)

GetCreativeTonies retrieves all Creative-Tonies in a specific household. Creative-Tonies are the figurines that can have custom audio content uploaded to them.

Parameters:

• household: The household to retrieve Creative-Tonies from

Returns a slice of Creative-Tonies or an error if the request fails.

Example:

households, _ := client.GetHouseholds()
tonies, err := client.GetCreativeTonies(&households[0])
if err != nil {
    log.Fatal(err)
}
for _, tonie := range tonies {
    fmt.Printf("Tonie: %s (Chapters: %d)\n", tonie.Name, tonie.ChaptersPresent)
}

func (*Client) GetHouseholds

func (c *Client) GetHouseholds() ([]Household, error)

GetHouseholds retrieves all households that the user belongs to. A household represents a family or group that shares Tonieboxes.

Returns a slice of households or an error if the request fails.

Example:

households, err := client.GetHouseholds()
if err != nil {
    log.Fatal(err)
}
for _, household := range households {
    fmt.Printf("Household: %s (ID: %s)\n", household.Name, household.ID)
}

func (*Client) GetMe

func (c *Client) GetMe() (*Me, error)

GetMe retrieves personal information about the authenticated user.

Returns the user's profile information or an error if the request fails.

Example:

me, err := client.GetMe()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("User: %s %s\n", me.FirstName, me.LastName)

func (*Client) Login

func (c *Client) Login(username, password string) (*JWTToken, error)

Login authenticates the user with their Toniebox account credentials. This must be called before any other API methods.

Parameters:

• username: The email address for your Toniebox account
• password: The password for your Toniebox account

Returns an error if authentication fails.

Example:

err := client.Login("user@example.com", "password")
if err != nil {
    log.Fatal(err)
}

Login authenticates the user with their Toniebox account credentials. This must be called before any other API methods.

Parameters:

• username: The email address for your Toniebox account
• password: The password for your Toniebox account

Returns the authentication token (including refresh token) or an error if authentication fails.

Example:

token, err := client.Login("user@example.com", "password")
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Refresh Token: %s\n", token.RefreshToken)

func (*Client) SetToken

func (c *Client) SetToken(token *JWTToken)

SetToken sets the authentication token directly, bypassing the login process. This is useful if you have a stored refresh token or access token.

Parameters:

• token: The JWT token to use

Example:

token := &toniebox.JWTToken{
    AccessToken: "...",
    RefreshToken: "...",
}
client.SetToken(token)

type CreativeTonie

type CreativeTonie struct {
	ID                string    `json:"id"`
	Name              string    `json:"name"`
	Live              bool      `json:"live"`
	Private           bool      `json:"private"`
	ImageURL          string    `json:"imageUrl"`
	TranscodingErrors []string  `json:"transcodingErrors"`
	Transcoding       bool      `json:"transcoding"`
	SecondsPresent    float64   `json:"secondsPresent"`
	SecondsRemaining  float64   `json:"secondsRemaining"`
	ChaptersPresent   int       `json:"chaptersPresent"`
	ChaptersRemaining int       `json:"chaptersRemaining"`
	Chapters          []Chapter `json:"chapters"`
	HouseholdID       string    `json:"householdId"`
	// contains filtered or unexported fields
}

CreativeTonie represents a Creative-Tonie figurine

func (*CreativeTonie) Commit

func (ct *CreativeTonie) Commit() error

Commit saves all changes made to this Creative-Tonie to the Toniebox cloud. This must be called after making changes like renaming, uploading, or deleting chapters.

Returns an error if the commit fails.

Example:

tonie.Name = "New Name"
err := tonie.Commit()
if err != nil {
    log.Fatal(err)
}

func (*CreativeTonie) DeleteChapter

func (ct *CreativeTonie) DeleteChapter(chapter *Chapter)

DeleteChapter removes a chapter from this Creative-Tonie. Note: You must call Commit() after this to persist the changes.

Parameters:

• chapter: The chapter to delete

Example:

chapter := tonie.FindChapterByTitle("Old Track")
if chapter != nil {
    tonie.DeleteChapter(chapter)
    tonie.Commit()
}

func (*CreativeTonie) FindChapterByTitle

func (ct *CreativeTonie) FindChapterByTitle(title string) *Chapter

FindChapterByTitle searches for a chapter with the given title on this Creative-Tonie.

Parameters:

• title: The title to search for

Returns the chapter if found, or nil if not found.

Example:

chapter := tonie.FindChapterByTitle("My Audio Track")
if chapter != nil {
    fmt.Printf("Found chapter: %s\n", chapter.Title)
}

func (*CreativeTonie) Refresh

func (ct *CreativeTonie) Refresh() error

Refresh reloads the current state of this Creative-Tonie from the Toniebox cloud. This is useful to see the latest changes, such as transcoding status.

Returns an error if the refresh fails.

Example:

err := tonie.Refresh()
if err != nil {
    log.Fatal(err)
}
fmt.Printf("Chapters present: %d\n", tonie.ChaptersPresent)

func (*CreativeTonie) UploadFile

func (ct *CreativeTonie) UploadFile(title, filePath string) error

UploadFile uploads an audio file to this Creative-Tonie. The file will be added as a new chapter with the specified title. Note: You must call Commit() after this to persist the changes.

Parameters:

• title: The title for the new chapter
• filePath: The path to the audio file to upload

Returns an error if the upload fails.

Example:

err := tonie.UploadFile("My Story", "/path/to/audio.mp3")
if err != nil {
    log.Fatal(err)
}
err = tonie.Commit()

type FieldsBean

type FieldsBean struct {
	Key               string `json:"key"`
	Policy            string `json:"policy"`
	XAmzAlgorithm     string `json:"x-amz-algorithm"`
	XAmzCredential    string `json:"x-amz-credential"`
	XAmzDate          string `json:"x-amz-date"`
	XAmzSignature     string `json:"x-amz-signature"`
	XAmzSecurityToken string `json:"x-amz-security-token"`
}

FieldsBean represents Amazon S3 upload form fields

type Household

type Household struct {
	ID                          string `json:"id"`
	Name                        string `json:"name"`
	Image                       string `json:"image"`
	ForeignCreativeTonieContent bool   `json:"foreignCreativeTonieContent"`
	Access                      string `json:"access"`
	CanLeave                    bool   `json:"canLeave"`
	OwnerName                   string `json:"ownerName"`
}

Household represents a Toniebox household

type JWTToken

type JWTToken struct {
	AccessToken  string `json:"access_token"`
	ExpiresIn    int    `json:"expires_in,omitempty"`
	RefreshToken string `json:"refresh_token,omitempty"`
	TokenType    string `json:"token_type,omitempty"`
	Scope        string `json:"scope,omitempty"`
}

JWTToken represents the authentication token returned by the API

type Login

type Login struct {
	Email    string `json:"email"`
	Password string `json:"password"`
}

Login represents the credentials for logging into the Toniebox API

type Me

type Me struct {
	Email                        string `json:"email"`
	UUID                         string `json:"uuid"`
	FirstName                    string `json:"firstName"`
	LastName                     string `json:"lastName"`
	Sex                          string `json:"sex"`
	AcceptedTermsOfUse           bool   `json:"acceptedTermsOfUse"`
	Tracking                     bool   `json:"tracking"`
	AuthCode                     string `json:"authCode"`
	ProfileImage                 string `json:"profileImage"`
	Verified                     bool   `json:"isVerified"`
	EduUser                      bool   `json:"isEduUser"`
	NotificationCount            int    `json:"notificationCount"`
	RequiresVerificationToUpload bool   `json:"requiresVerificationToUpload"`
}

Me represents personal information about the authenticated user

type RequestBean

type RequestBean struct {
	URL    string     `json:"url"`
	Fields FieldsBean `json:"fields"`
}

RequestBean represents Amazon S3 upload request details