FiguraHostBridge

A local ASP.NET Core Web API bridge for communication with a Figura avatar script over HTTP (Lua).

This project is intended to run on your machine and expose lightweight endpoints your Figura script can call using Figura's built-in HTTP networking.

What this API provides

• Time and Date endpoints for the server's local clock and timezone information
• Spotify integration:
  • Search (tracks, artists, albums)
  • Track details
  • User authentication (Authorization Code flow) and token refresh
  • Player controls (play, pause, next, previous, set volume) and device listing
• Consistent JSON response envelope (success, message, data, timestamp, errorCode)
• Encrypted persistent storage for Spotify user tokens

Default host (configured in Program.cs):

• http://localhost:80

Note: the host URL can be changed in Program.cs or via environment/configuration when hosting.

Endpoints

Base route prefix: api

Time and Date:

• GET /api/time/time
• GET /api/time/date

Spotify (public client credentials + user flows):

• GET /api/spotify/search?query=<text>&limit=<1-50> - search tracks
• GET /api/spotify/search/artists?query=<text>&limit=<1-50> - search artists
• GET /api/spotify/search/albums?query=<text>&limit=<1-50> - search albums
• GET /api/spotify/tracks/{trackId} - get track details

Authentication / user tokens:

• GET /api/spotify/auth/login?state={optional}&redirectUri={optional}&scopes={optional} - build authorization URL
• GET /api/spotify/auth/callback?code={code}&state={state} - authorization callback (also mounted at /api/spotify/callback)
• POST /api/spotify/auth/refresh - refresh user access token (JSON body: { "refreshToken": "..." })

Player / user playback (require user access token via Authorization: Bearer or stored token):

• GET /api/spotify/player/devices - list available devices for the authenticated user
• GET /api/spotify/player/now-playing - get currently playing track (may return null)
• POST /api/spotify/player/next - skip to next track
• POST /api/spotify/player/previous - skip to previous track
• PUT /api/spotify/player/pause - pause playback
• PUT /api/spotify/player/play - resume playback
• PUT /api/spotify/player/volume?volumePercent={0-100}&deviceId={optional} - set volume

Example:

• GET http://localhost:80/api/spotify/search?query=porter%20robinson&limit=5

Authentication & token storage

This project supports the Spotify Authorization Code flow for user-scoped operations. Use the /api/spotify/auth/login endpoint to obtain an authorization URL and complete the OAuth redirect flow.

Once exchanged, user tokens are stored encrypted using ASP.NET Core Data Protection under:

• %LocalAppData%\FiguraHostBridge\spotify-user-token.dat (Windows)

The token store automatically refreshes access tokens when needed. If no valid token is available, endpoints requiring user scope will return an unauthorized response and you must re-authenticate.

Environment variables

Configuration is loaded from environment variables (DotNetEnv loads a local .env file in development). The following are required for Spotify functionality:

• SPOTIFY_CLIENT_ID
• SPOTIFY_CLIENT_SECRET
• SPOTIFY_REDIRECT_URI (used when building the authorization URL or exchanging codes if not supplied on the request)

Example .env:

SPOTIFY_CLIENT_ID=your_client_id
SPOTIFY_CLIENT_SECRET=your_client_secret
SPOTIFY_REDIRECT_URI=http://localhost:80/api/spotify/auth/callback

Running locally

Requirements:

• .NET SDK compatible with net10.0

Run:

dotnet restore
dotnet run

The app enables Swagger in development at /swagger (e.g. http://localhost:80/swagger).

Notes:

• Program.cs currently calls Env.Load() to read a .env file and registers Data Protection. It also contains commented code for running as a Windows Service.
• The app listens on port 80 by default (change as needed).

Figura + Lua usage notes

• Figura only allows local HTTP endpoints with port 80, so this API is designed to run locally and listen on that port.
• Handle request failures/timeouts in Lua to keep avatar logic stable.

---

Technology sources / references

Figura / Lua scripting

• FiguraMC GitHub: https://github.com/FiguraMC/Figura
• Figura documentation: https://figura-wiki.pages.dev/

.NET / ASP.NET Core

• ASP.NET Core Web API docs: https://learn.microsoft.com/aspnet/core/web-api/
• .NET documentation: https://learn.microsoft.com/dotnet/

Spotify

• Spotify Web API overview: https://developer.spotify.com/documentation/web-api
• Client Credentials flow: https://developer.spotify.com/documentation/web-api/tutorials/client-credentials-flow

Libraries used in this project

• DotNetEnv (NuGet): https://www.nuget.org/packages/DotNetEnv
• Swashbuckle.AspNetCore (Swagger for ASP.NET Core): https://www.nuget.org/packages/Swashbuckle.AspNetCore
• SpotifyAPI.Web (NuGet): https://www.nuget.org/packages/SpotifyAPI.Web