@hansogj/discogs-item-lookup
v1.6.0
Published
A CLI and library to look up item details from the Discogs API.
Maintainers
Readme
Discogs Item Lookup
A CLI and library to look up information about a specific music release from the Discogs API.
Features
- Artist Name: Get the credited artists for the release (
artists), and every credit joined as Discogs shows it (artistCredit, when several). - Item Title: Find the album or single name.
- Tracklist: View the complete tracklist for the specific release version, with durations and track credits. A suite listed with sub-tracks (an index entry) is one track.
- Genres, country and personnel:
genres,styles,country,extraartists. - Release Years: See both the year for this specific release and the year of the original master release.
- Direct Link: A convenient link to view the release directly on the Discogs website.
Installation
npm install -g @hansogj/discogs-item-lookupCLI Usage
After installation, you can use the discogs-lookup command.
discogs-lookup <release-id> [options]Arguments:
<release-id>: The Discogs release ID (e.g.,249504orr249504), a master ID (e.g.,m1439, resolved to the master's main release), or a discogs.com release/master URL.masterYearis the original release year from the master (falls back to the release year).
Options:
-t, --token <token>: Discogs personal access token. This overrides theDISCOGS_TOKENenvironment variable.-h, --help: display help for command.-V, --version: output the version number.
Example:
discogs-lookup 249504 // or
pnpm run cli 249504This will output the release information for Rick Astley's "Never Gonna Give You Up" .
Library Usage
You can also use this package as a library in your own Node.js projects.
import { lookupRelease, DiscogsApiError } from '@hansogj/discogs-item-lookup';
async function getReleaseInfo() {
try {
const data = await lookupRelease({
releaseId: '249504',
// token: 'your-discogs-token', // optional, will use env if not provided
// disc: 2, // optional, to get only a specific disc
});
console.log(data);
} catch (error) {
if (error instanceof DiscogsApiError) {
console.error(`API Error: ${error.message}`);
} else {
console.error('An unexpected error occurred:', error);
}
}
}
getReleaseInfo();artist (every credited artist joined with , ) is deprecated: use artists[0] or artistCredit.
Formatting helpers
@hansogj/discogs-item-lookup/format holds the pure helpers that music-utils and music-audit share, with no network or environment access:
cleanArtistName(name): drops Discogs'(n)suffix (Dave Greenslade (2)→Dave Greenslade).joinArtistCredit(artists): every credited artist with Discogs'joins;/becomes,(Patrick Woodroffe, Dave Greenslade), so the name fits a folder name.flattenTracklist(tracklist): index entries as one track (position from the first sub-track), headings dropped.formatInfoTxt(release, artistName, disc?): theinfo.txttext:Artist - Title (year), reissue year, country, songs with composers and durations, personnel, thenDiscogs-Release:/Discogs-Master:/Disc:lines.
The same helpers are exported from the package root too.
Configuration
This tool requires a Discogs Personal Access Token to communicate with the Discogs API. The token can be provided in one of two ways:
- Environment Variable (recommended): Create a
.envfile in your project root and addDISCOGS_TOKEN=your_token_here. - CLI Option: Use the
--tokenor-tflag when running the command.
Getting a Discogs Token
- Log in to your Discogs account.
- Go to your Developer Settings.
- Click "Generate new token".
- Use this token for the
DISCOGS_TOKENenvironment variable or the--tokenoption.
...
