Teal.fm

teal.fm is a social discovery and browsing app for scrobbles stored in your Atmosphere Account.

How does that work?

Your Atmosphere Account consists of social data (it’s just JSON) stored in a personal repository on a PDS (Personal Data Server), all of which is standardized under the AT Protocol.

The AT Protocol defines how your data is stored, how you authenticate to write to it, and how indpendent apps share and consume it. Critically, each layer (data storage, app, communication) of the AT Protocol can be operated by indpendent entities so your data and experience not locked behind a walled garden.

Although each layer can be implemented separately (you can self-host everything!), it is normally a simple process for an end-user to create and start using an Atmosphere Account as many apps can do everything for you. The most common example being a Bluesky, but there are other public account providers.

When Multi-Scrobbler uses the AT Protocol…

multi-scrobbler “scrobbles” (writes) your plays to your repository
- in a JSON data structure which includes teal.fm’s data type and structure
- at a known location for teal.fm’s data (fm.teal), in a list that is appended to as you continue to scrobble
when accessing teal.fm, or another application that knows how to read it, your data is pulled from the repository to render their app

Your Data Is Public

Atproto PDS access is public, meaning your scrobbles are also public (read-only). This isn’t any different than using Last.fm or Listenbrainz, in terms of privacy.

teal.fm Is Still In Development

teal.fm is still in developement and does not have a true production website, yet.

To view your teal.fm scrobble data you can:

use yearinmusic.teal.fm or wrapped.baileytownsend.dev for wrapped-style stats of your teal.fm scrobbles
use atproto.at to view the raw data (convenience URLs are generated in multi-scrobbler, per scrobble, for you to do this)

Setup

Navigate to the Account settings for your Atmosphere account on your respective PDS and create a new App Password.

If you don’t know what a PDS is or how to find this just use Bluesky:

Sign in to Bluesky with your Atmosphere account
Navigate to https://bsky.app/settings/app-passwords
- Settings -> Privacy and Security -> App passwords
Create a new App Password and save it somewhere, it will not be shown again

Configuration

Determining Your Atmosphere Handle/Identifier

Your Atmosphere identifier/handle should be either:

A valid DID, starting with did:plc:... or did:web:...
Your full Atmosphere Account ATProto handle, including TLD

If using a handle:

For regular Bluesky account this will be like: alice.bsky.social
For Bluesky accounts that use their domain as their account this is your domain: mydomain.com
For non-Bluesky-PDS users, you probably already know your handle

If your identifier does not look like a DID and does not include a TLD then multi-scrobbler will automatically append .bsky.social to your handle value.

Configuration Type

This is configuration for the ENV Config Type.

Environmental Variable	Type	Default	Description
`TEALFM_ID`	string		A globally unique ID EX `myComponentId`
`TEALFM_NAME`	string	Value of `TEALFM_ID`	A vanity name EX `My Cool Component`
`TEALFM_ENABLE`	boolean	true	Should this component be used?
`TEALFM_IDENTIFIER`	string		The fully-qualified handle, or identifier, for your Atmosphere account
`TEALFM_APP_PW`	string		The App Password you created for your Atmosphere account

Bold/Italic = Required

Config Structure

This displays the structure of the File Configuration for a tealfm type Client with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Config Example

This displays an example config file of a tealfm Client File Configuration that adheres to the shown Config Structure.

text mode lets you edit the JSON directly.
tree mode gives you a guided point-and-click editing experience that always keeps the JSON syntax valid.

Both modes validate that the configuration is correct. Any errors show up as squiggly lines.

After you finish editing, switch to text and then copy all text to get a completed config.

Config Example Mobile Experience

This displays an example config file of a tealfm Client File Configuration that adheres to the shown Config Structure.

The example config file editor is meant for a larger screen experience so only the read-only example is shown. Please use this site on a tablet/laptop/desktop to enable file editor features.

[
  {
    "id": "myTealClient",
    "name": "Foxx Teal Client",
    "data": {
      "identifier": "alice.bsky.social",
      "appPassword": "twog-phu7-4dhe-y4j3"
    },
    "configureAs": "client"
  }
]

Config Structure

This displays the structure of the all-in-one (config.json) configuration with all possible properties, their shape, and descriptions/types. Use this to understand how to write a valid config.

Select the tealfm type from the respective clients node below, then expand it.