anthias

package module
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Jul 8, 2026 License: MIT Imports: 15 Imported by: 0

README

anthias-go

CI

Go SDK for the Anthias digital signage player v2 REST API.

Install

go get github.com/atakanatamert/anthias-go

Quickstart

ctx := context.Background()

client, err := anthias.New("http://192.168.1.50")
if err != nil {
	return err
}

assets, err := client.ListAssets(ctx)
if err != nil {
	return err
}
_ = assets

Authentication

Use HTTP Basic Auth when the player has the auth_basic backend enabled.

client, err := anthias.New(
	"http://192.168.1.50",
	anthias.WithBasicAuth("admin", "password"),
)

Upload With Progress

Uploads stream the body and set Content-Length; pass a generous context timeout for large files.

ctx, cancel := context.WithTimeout(context.Background(), time.Hour)
defer cancel()

upload, err := client.UploadFileReader(
	ctx,
	strings.NewReader("hello"),
	"hello.txt",
	5,
	anthias.WithProgress(func(sent, total int64) {
		_ = float64(sent) / float64(total)
	}),
)
if err != nil {
	return err
}
_ = upload

Playback Control

if err := client.ControlPlayback(ctx, anthias.PlaybackNext); err != nil {
	return err
}

if err := client.ControlPlayback(ctx, anthias.PlaybackAsset("asset-id")); err != nil {
	return err
}

Methods

Method Anthias endpoint
ListAssets(ctx) GET /api/v2/assets
GetAsset(ctx, assetID) GET /api/v2/assets/{id}
CreateAsset(ctx, req) POST /api/v2/assets
UpdateAsset(ctx, assetID, req) PATCH /api/v2/assets/{id}
ReplaceAsset(ctx, assetID, req) PUT /api/v2/assets/{id}
DeleteAsset(ctx, assetID) DELETE /api/v2/assets/{id}
SetPlaylistOrder(ctx, assetIDs) POST /api/v2/assets/order
ControlPlayback(ctx, command) GET /api/v2/assets/control/{command}
GetAssetContent(ctx, assetID) GET /api/v2/assets/{id}/content
UploadFile(ctx, path, opts...) POST /api/v2/file_asset
UploadFileReader(ctx, r, filename, size, opts...) POST /api/v2/file_asset
GetDeviceSettings(ctx) GET /api/v2/device_settings
UpdateDeviceSettings(ctx, req) PATCH /api/v2/device_settings
Backup(ctx) POST /api/v2/backup
Recover(ctx, r, filename, size) POST /api/v2/recover
Reboot(ctx) POST /api/v2/reboot
Shutdown(ctx) POST /api/v2/shutdown
GetInfo(ctx) GET /api/v2/info
GetIntegrations(ctx) GET /api/v2/integrations

Compatibility

anthias-go targets the Anthias v2 API and uses only the Go standard library.

Acknowledgements

Anthias is an open source digital signage platform maintained by Screenly. This project is an independent client library and is not affiliated with or endorsed by Screenly.

Contributing

See CONTRIBUTING.md. This project is released under the MIT License.

Documentation

Overview

Package anthias is a Go client SDK for the Anthias digital signage player's v2 REST API.

Create a client with New and call its methods. Every method takes a context.Context as its first parameter. 

client, err := anthias.New("http://192.168.1.50")
if err != nil { /* ... */ }
assets, err := client.ListAssets(ctx)

Authentication, when enabled on the player, uses HTTP Basic Auth via WithBasicAuth. Non-2xx responses are returned as *APIError; use errors.As to inspect them.

File uploads (Client.UploadFile, Client.UploadFileReader) stream without buffering the whole file and report progress via WithProgress. Uploads honor the request context; for large files pass a generous context.WithTimeout, since a short client-wide timeout (see WithTimeout) may abort long transfers.

Index

Constants

View Source 
const Version = "0.1.0"

Version is the current SDK version.

Variables

This section is empty.

Functions

func Ptr 

func Ptr[T any](v T) *T

Ptr returns a pointer to v. Useful for populating pointer request fields.

Types

type APIError 

type APIError struct {
	StatusCode int
	Method     string
	URL        string
	Body       []byte // raw response body (possibly truncated to 64 KiB)
}

APIError represents a non-2xx response from the Anthias API.

func (*APIError) Error 

func (e *APIError) Error() string

func (*APIError) IsNotFound 

func (e *APIError) IsNotFound() bool

IsNotFound reports whether the error is a 404 response.

type Asset 

type Asset struct {
	AssetID        string    `json:"asset_id"`
	Name           string    `json:"name"`
	URI            string    `json:"uri"`
	StartDate      time.Time `json:"start_date"`
	EndDate        time.Time `json:"end_date"`
	Duration       int       `json:"duration"`
	Mimetype       string    `json:"mimetype"`
	IsEnabled      bool      `json:"is_enabled"`
	NoCache        bool      `json:"nocache"`
	PlayOrder      int       `json:"play_order"`
	SkipAssetCheck bool      `json:"skip_asset_check"`
	IsActive       bool      `json:"is_active"`
	IsProcessing   bool      `json:"is_processing"`
}

Asset is returned by list/get/create/update/replace.

type AssetContent 

type AssetContent struct {
	Type     string `json:"type"`
	URL      string `json:"url,omitempty"`
	Filename string `json:"filename,omitempty"`
	Mimetype string `json:"mimetype,omitempty"`
	Content  string `json:"content,omitempty"`
}

AssetContent is returned by GET /api/v2/assets/{id}/content. Type is "file" or "url". For "file", Filename, Mimetype and Content (base64) are set. For "url", URL is set.

type Client 

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

Client is an Anthias v2 API client. Construct one with New.

func New 

func New(baseURL string, opts ...Option) (*Client, error)

New creates a Client for the player at baseURL. baseURL must include a scheme (e.g. "http://192.168.1.50" or "http://player.local:8080"); a trailing slash is trimmed.

func (*Client) Backup 

func (c *Client) Backup(ctx context.Context) (string, error)

Backup triggers a backup on the player and returns the resulting backup filename.

func (*Client) ControlPlayback 

func (c *Client) ControlPlayback(ctx context.Context, command PlaybackCommand) error

ControlPlayback sends a playback command (next/previous/asset).

func (*Client) CreateAsset 

func (c *Client) CreateAsset(ctx context.Context, req CreateAssetRequest) (*Asset, error)

CreateAsset creates a new asset.

func (*Client) DeleteAsset 

func (c *Client) DeleteAsset(ctx context.Context, assetID string) error

DeleteAsset deletes an asset.

func (*Client) GetAsset 

func (c *Client) GetAsset(ctx context.Context, assetID string) (*Asset, error)

GetAsset fetches a single asset by ID.

func (*Client) GetAssetContent 

func (c *Client) GetAssetContent(ctx context.Context, assetID string) (*AssetContent, error)

GetAssetContent fetches an asset's content (file bytes or URL).

func (*Client) GetDeviceSettings 

func (c *Client) GetDeviceSettings(ctx context.Context) (*DeviceSettings, error)

GetDeviceSettings fetches the player's device settings.

func (*Client) GetInfo 

func (c *Client) GetInfo(ctx context.Context) (*Info, error)

GetInfo fetches player runtime information.

func (*Client) GetIntegrations 

func (c *Client) GetIntegrations(ctx context.Context) (*Integrations, error)

GetIntegrations fetches player integration information (e.g. balena).

func (*Client) ListAssets 

func (c *Client) ListAssets(ctx context.Context) ([]Asset, error)

ListAssets lists all assets.

func (*Client) Reboot 

func (c *Client) Reboot(ctx context.Context) error

Reboot asks the player to reboot.

func (*Client) Recover 

func (c *Client) Recover(ctx context.Context, r io.Reader, filename string, size int64) error

Recover restores a backup by uploading it (multipart field "backup_upload"). filename sets the uploaded part's filename. size must be the exact payload length so the request uses Content-Length rather than chunked transfer encoding. The payload is streamed and never buffered.

Recover honors ctx; pass a generous context.WithTimeout for large backups.

func (*Client) ReplaceAsset 

func (c *Client) ReplaceAsset(ctx context.Context, assetID string, req CreateAssetRequest) (*Asset, error)

ReplaceAsset replaces an asset (full update).

func (*Client) SetPlaylistOrder 

func (c *Client) SetPlaylistOrder(ctx context.Context, assetIDs []string) error

SetPlaylistOrder reorders assets. assetIDs is sent form-encoded as a comma-joined "ids" value.

func (*Client) Shutdown 

func (c *Client) Shutdown(ctx context.Context) error

Shutdown asks the player to shut down.

func (*Client) UpdateAsset 

func (c *Client) UpdateAsset(ctx context.Context, assetID string, req UpdateAssetRequest) (*Asset, error)

UpdateAsset partially updates an asset.

func (*Client) UpdateDeviceSettings 

func (c *Client) UpdateDeviceSettings(ctx context.Context, req UpdateDeviceSettingsRequest) error

UpdateDeviceSettings partially updates device settings.

func (*Client) UploadFile 

func (c *Client) UploadFile(ctx context.Context, path string, opts ...UploadOption) (*FileUpload, error)

UploadFile uploads the file at path to POST /api/v2/file_asset (multipart field "file_upload"). The file is streamed and never fully buffered.

Uploads honor ctx; pass a generous context.WithTimeout for large files, since a short client-wide timeout (see WithTimeout) may abort long transfers.

func (*Client) UploadFileReader 

func (c *Client) UploadFileReader(ctx context.Context, r io.Reader, filename string, size int64, opts ...UploadOption) (*FileUpload, error)

UploadFileReader uploads the contents of r as filename (size bytes) to POST /api/v2/file_asset (multipart field "file_upload"). size must be the exact content length so the request uses Content-Length rather than chunked transfer encoding (some proxies mishandle chunked uploads).

Uploads honor ctx; pass a generous context.WithTimeout for large files.

type CreateAssetRequest 

type CreateAssetRequest struct {
	Name           string    `json:"name"`
	URI            string    `json:"uri"`
	Ext            string    `json:"ext,omitempty"` // write-only; from a file upload response
	StartDate      time.Time `json:"start_date"`
	EndDate        time.Time `json:"end_date"`
	Duration       int       `json:"duration"`
	Mimetype       string    `json:"mimetype"`
	IsEnabled      bool      `json:"is_enabled"`
	IsProcessing   *bool     `json:"is_processing,omitempty"`
	NoCache        *bool     `json:"nocache,omitempty"`
	PlayOrder      *int      `json:"play_order,omitempty"`
	SkipAssetCheck *bool     `json:"skip_asset_check,omitempty"`
}

CreateAssetRequest is the body of POST /api/v2/assets and PUT /api/v2/assets/{id}. Required by the server: name, uri, start_date, end_date, duration, mimetype, is_enabled.

type DeviceSettings 

type DeviceSettings struct {
	PlayerName               string `json:"player_name"`
	AudioOutput              string `json:"audio_output"`
	DefaultDuration          int    `json:"default_duration"`
	DefaultStreamingDuration int    `json:"default_streaming_duration"`
	DateFormat               string `json:"date_format"`
	AuthBackend              string `json:"auth_backend"`
	ShowSplash               bool   `json:"show_splash"`
	DefaultAssets            bool   `json:"default_assets"`
	ShufflePlaylist          bool   `json:"shuffle_playlist"`
	Use24HourClock           bool   `json:"use_24_hour_clock"`
	DebugLogging             bool   `json:"debug_logging"`
	Username                 string `json:"username"`
}

DeviceSettings is returned by GET /api/v2/device_settings.

type FileUpload 

type FileUpload struct {
	URI string `json:"uri"`
	Ext string `json:"ext"`
}

FileUpload is the response of POST /api/v2/file_asset.

type Info 

type Info struct {
	Viewlog        string   `json:"viewlog"`
	Loadavg        float64  `json:"loadavg"`
	FreeSpace      string   `json:"free_space"`
	DisplayPower   *string  `json:"display_power"` // nullable
	UpToDate       bool     `json:"up_to_date"`
	AnthiasVersion string   `json:"anthias_version"`
	DeviceModel    string   `json:"device_model"`
	Uptime         Uptime   `json:"uptime"`
	Memory         Memory   `json:"memory"`
	IPAddresses    []string `json:"ip_addresses"`
	MACAddress     string   `json:"mac_address"`
	HostUser       string   `json:"host_user"`
}

Info is returned by GET /api/v2/info.

type Integrations 

type Integrations struct {
	IsBalena                bool    `json:"is_balena"`
	BalenaDeviceID          *string `json:"balena_device_id,omitempty"`
	BalenaAppID             *string `json:"balena_app_id,omitempty"`
	BalenaAppName           *string `json:"balena_app_name,omitempty"`
	BalenaSupervisorVersion *string `json:"balena_supervisor_version,omitempty"`
	BalenaHostOSVersion     *string `json:"balena_host_os_version,omitempty"`
	BalenaDeviceNameAtInit  *string `json:"balena_device_name_at_init,omitempty"`
}

Integrations is returned by GET /api/v2/integrations.

type Memory 

type Memory struct {
	Total     int `json:"total"`
	Used      int `json:"used"`
	Free      int `json:"free"`
	Shared    int `json:"shared"`
	Buff      int `json:"buff"`
	Available int `json:"available"`
}

Memory is the memory usage reported by GET /api/v2/info.

type Option 

type Option func(*Client)

Option configures a Client.

func WithBasicAuth 

func WithBasicAuth(username, password string) Option

WithBasicAuth enables HTTP Basic Auth (Anthias auth_basic backend).

func WithHTTPClient 

func WithHTTPClient(hc *http.Client) Option

WithHTTPClient sets the underlying *http.Client used for requests. Default: &http.Client{Timeout: 30s}.

func WithTimeout 

func WithTimeout(d time.Duration) Option

WithTimeout sets the timeout on the client's *http.Client.

func WithUserAgent 

func WithUserAgent(ua string) Option

WithUserAgent overrides the default User-Agent header.

type PlaybackCommand 

type PlaybackCommand string

PlaybackCommand is a playlist control command for Client.ControlPlayback. 

const (
	// PlaybackNext skips to the next asset.
	PlaybackNext PlaybackCommand = "next"
	// PlaybackPrevious returns to the previous asset.
	PlaybackPrevious PlaybackCommand = "previous"
)

func PlaybackAsset 

func PlaybackAsset(assetID string) PlaybackCommand

PlaybackAsset switches playback to the given asset. The resulting command is path-escaped before being sent.

type UpdateAssetRequest 

type UpdateAssetRequest struct {
	Name           *string    `json:"name,omitempty"`
	URI            *string    `json:"uri,omitempty"`
	StartDate      *time.Time `json:"start_date,omitempty"`
	EndDate        *time.Time `json:"end_date,omitempty"`
	Duration       *int       `json:"duration,omitempty"`
	Mimetype       *string    `json:"mimetype,omitempty"`
	IsEnabled      *bool      `json:"is_enabled,omitempty"`
	IsProcessing   *bool      `json:"is_processing,omitempty"`
	NoCache        *bool      `json:"nocache,omitempty"`
	SkipAssetCheck *bool      `json:"skip_asset_check,omitempty"`
}

UpdateAssetRequest is the body of PATCH /api/v2/assets/{id} (partial update). All fields are pointers with omitempty.

type UpdateDeviceSettingsRequest 

type UpdateDeviceSettingsRequest struct {
	PlayerName               *string `json:"player_name,omitempty"`
	AudioOutput              *string `json:"audio_output,omitempty"`
	DefaultDuration          *int    `json:"default_duration,omitempty"`
	DefaultStreamingDuration *int    `json:"default_streaming_duration,omitempty"`
	DateFormat               *string `json:"date_format,omitempty"`
	ShowSplash               *bool   `json:"show_splash,omitempty"`
	DefaultAssets            *bool   `json:"default_assets,omitempty"`
	ShufflePlaylist          *bool   `json:"shuffle_playlist,omitempty"`
	Use24HourClock           *bool   `json:"use_24_hour_clock,omitempty"`
	DebugLogging             *bool   `json:"debug_logging,omitempty"`
	Username                 *string `json:"username,omitempty"`
	Password                 *string `json:"password,omitempty"`
	Password2                *string `json:"password_2,omitempty"`
	AuthBackend              *string `json:"auth_backend,omitempty"` // "" or "auth_basic"
	CurrentPassword          *string `json:"current_password,omitempty"`
}

UpdateDeviceSettingsRequest is the body of PATCH /api/v2/device_settings. All fields are optional.

type UploadOption 

type UploadOption func(*uploadOptions)

UploadOption configures an upload.

func WithProgress 

func WithProgress(fn UploadProgress) UploadOption

WithProgress registers a progress callback. It is invoked on the first read, at most every ~500ms thereafter, and once at completion.

type UploadProgress 

type UploadProgress func(sent, total int64)

UploadProgress receives cumulative bytes sent and the total request body size during an upload.

type Uptime 

type Uptime struct {
	Days  int     `json:"days"`
	Hours float64 `json:"hours"`
}

Uptime is the uptime reported by GET /api/v2/info.

Source Files

View all Source files

Directories

Path Synopsis
examples
basic command

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.