{"id":15364169,"url":"https://github.com/kellnerd/listenbrainz-ts","last_synced_at":"2025-04-15T09:29:57.184Z","repository":{"id":215003892,"uuid":"737875745","full_name":"kellnerd/listenbrainz-ts","owner":"kellnerd","description":"ListenBrainz API client and listen parsers","archived":false,"fork":false,"pushed_at":"2024-12-01T17:25:35.000Z","size":132,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":2,"default_branch":"main","last_synced_at":"2025-03-28T18:51:49.480Z","etag":null,"topics":["api-client","deno","listenbrainz","typescript"],"latest_commit_sha":null,"homepage":"https://jsr.io/@kellnerd/listenbrainz","language":"TypeScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/kellnerd.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2024-01-01T20:13:27.000Z","updated_at":"2025-02-11T13:54:59.000Z","dependencies_parsed_at":"2024-03-14T17:25:15.802Z","dependency_job_id":"b7a203d1-fc1b-43e4-b4ae-d79609a5baad","html_url":"https://github.com/kellnerd/listenbrainz-ts","commit_stats":null,"previous_names":["kellnerd/listenbrainz-ts"],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Flistenbrainz-ts","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Flistenbrainz-ts/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Flistenbrainz-ts/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/kellnerd%2Flistenbrainz-ts/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/kellnerd","download_url":"https://codeload.github.com/kellnerd/listenbrainz-ts/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":249042668,"owners_count":21203332,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["api-client","deno","listenbrainz","typescript"],"created_at":"2024-10-01T13:10:27.604Z","updated_at":"2025-04-15T09:29:57.156Z","avatar_url":"https://github.com/kellnerd.png","language":"TypeScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# listenbrainz\n\nTypeScript library to access the [ListenBrainz API].\n\nYou can use it to submit your listening history to your [ListenBrainz] account with your own apps.\n\nFor end users, there is also the [elbisaur] CLI, which exposes many features of the library to the command line.\nIn addition to showcasing the usage of the API client, it also has advanced features to manage listens.\n\n## Features\n\n- Submits listens and playing now notifications\n- Browses your listening history and allows you to delete listens\n- Handles ListenBrainz authorization and API errors\n- Adheres to rate limits and optionally retries failed requests\n- Provides generic `GET` and `POST` methods for (yet) unsupported API endpoints\n- Includes additional [parsers](#parsers) to extract listens from text formats\n- Ships with type definitions and inline [documentation]\n\nAs this library only makes use of web standards, it is also compatible with modern browsers (after transpilation to JavaScript).\n\n## Usage\n\nIn order to submit listens, you have to specify a user token which you can obtain from your [ListenBrainz settings] page.\n\nThe following example instantiates a ListenBrainz client with a token from an environment variable and submits a [playing now] notification for a track:\n\n```ts\nimport { ListenBrainzClient } from \"@kellnerd/listenbrainz\";\n\nconst client = new ListenBrainzClient({ userToken: Deno.env.get(\"LB_TOKEN\") });\nawait client.playingNow({ artist_name: \"John Doe\", track_name: \"Love Song\" });\n```\n\n## Parsers\n\nAll listen parsers accept text input and generate `Listen` objects as their output.\nThese objects can then be used together with the ListenBrainz API and the LB client.\nNone of the parsers performs any filtering of listens, so you have to detect potential duplicates and skipped listens yourself.\n\nThe parsers do not include any logic to access files to make them platform independent.\nYou can pass them the content from a HTTP response body or from a file, for example.\n\nThe following parsers are available in the `listenbrainz/parser/*` submodules:\n\n- **JSON**: Accepts a JSON-serialized `Listen` object (as shown by the LB “Inspect listen” dialog) or an array of `Listen` objects as input.\n- **JSONL**: Multiple JSON-serialized `Listen` objects, separated by line breaks (format of listens files from a [LB listening history export]).\n- **MusicBrainz**: Accepts a release from the [MusicBrainz] JSON API and creates listens for the selected tracks.\n- **.scrobbler.log**: TSV table document which is generated by some portable music players for later submission to Last.fm.\n  - Parser currently accepts files with `AUDIOSCROBBLER/1.1` header which are generated by players with [Rockbox] firmware, possibly also by others.\n  - Automatically converts timestamps from your local timezone to UTC (as Rockbox players are usually not timezone-aware).\n  - Skipped listens are marked with `track_metadata.additional_info.skipped = true`.\n- **Spotify**: JSON files from an Extended Streaming History download.\n  - Calculates the correct listen (start) timestamp from stream end time and duration.\n  - Makes use of the “offline” timestamp to detect extreme outliers where Spotify has only logged a stream as ended when the app was next opened.\n  - Skipped listens can be detected by their `track_metadata.additional_info` attributes `skipped`, `reason_end` and a too short `duration_ms`.\n\n[documentation]: https://jsr.io/@kellnerd/listenbrainz/doc\n[elbisaur]: https://github.com/kellnerd/elbisaur\n[MusicBrainz]: https://musicbrainz.org/\n[ListenBrainz]: https://listenbrainz.org/\n[ListenBrainz API]: https://listenbrainz.readthedocs.io/en/latest/users/api/index.html\n[ListenBrainz settings]: https://listenbrainz.org/settings/\n[LB listening history export]: https://listenbrainz.org/settings/export/\n[playing now]: https://listenbrainz.org/listening-now/\n[Rockbox]: https://www.rockbox.org/wiki/LastFMLog\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkellnerd%2Flistenbrainz-ts","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fkellnerd%2Flistenbrainz-ts","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fkellnerd%2Flistenbrainz-ts/lists"}