VYBE music in your app, in minutes

Install

Add one script and one element. That is a complete music section: search, VYBE filters, songs and a player.

<script src="https://vybemusic.com/sdk/v1/vybe-sdk.js" data-key="vybe_pub_YOUR_KEY" data-theme="dark"></script>

<vybe-browser title="Music"></vybe-browser>

Use /sdk/v1/ to get fixes in version 1 automatically, or https://vybemusic.com/sdk/1.1.0/vybe-sdk.js to pin this exact version. You can also host the file from the download yourself.

Keys

Elements

Standard web components. They work in plain HTML, React, Vue, Svelte, Angular and in app webviews, and they all share one player, so a song started in one shows up in the others.

<vybe-vybes for="songs"></vybe-vybes>
<vybe-tracks id="songs" vybe="hype" bpm-min="118" bpm-max="128" layout="grid"></vybe-tracks>
<vybe-player></vybe-player>
<vybe-mini-player fixed></vybe-mini-player>

Events: vybe-play (detail.track), vybe-change (detail.vybe), vybe-loaded (detail.tracks).

Look and feel

Every element takes theme="dark", "light" or "auto" (follows the device). Match your brand with accent, radius and font in init, with CSS variables, or style the outer card with ::part(card).

VybeSDK.init({ key: 'vybe_pub_YOUR_KEY', theme: 'auto', accent: '#5B45E8', radius: 20, font: 'Inter, sans-serif' });

/* or in CSS */
:root { --vybe-accent: #5B45E8; --vybe-radius: 20px; }
vybe-browser::part(card) { box-shadow: 0 20px 60px -20px rgba(0,0,0,.5); }

Script API

const vybe = VybeSDK.init({ key: 'vybe_pub_YOUR_KEY' });

const { data, next_cursor } = await vybe.tracks.list({ vybe: 'chill', bpm_min: 90, bpm_max: 110, limit: 20 });
const found = await vybe.tracks.search('night drive');
const song = await vybe.tracks.get(data[0].id);       // with lyrics and their sections
song.display_artist;                                   // "Luna Waves & Ayo feat. Kai"
song.people.producers;                                 // ["DJ Pulse"]
song.lyrics.structure;                                 // ["Intro", "Verse 1", "Hook", ...]
const artist = await vybe.artists.get('luna-waves');
const vybes = await vybe.vybes();                      // [{ id, name, line }]

Results are cached for a minute, and calls retry on their own when the network blips or the limit is hit. TypeScript types come in vybe-sdk.d.ts.

Player

const p = VybeSDK.player;
p.playTrack(song, list);              // play a song with the rest of the list as the queue
p.toggle(); p.next(); p.prev(); p.seek(30); p.shuffle(); p.repeat = 'all'; p.setVolume(0.8);
p.on('trackchange', ({ track }) => {});
p.on('time', ({ time, duration }) => {});
p.on('error', ({ message }) => {});

The player picks the best format the device can play (Opus, AAC or MP3), shows the song on the lock screen and in system media controls, reuses media links until they expire, and reports plays for you: a play counts after 30 seconds of real listening.

Apps and signed-in users

Option 1, publishable key with your app id. Add your bundle id or package name to the key and pass it in init: VybeSDK.init({ key, app: 'com.yourapp.ios' }).

Option 2, session tokens (best for apps). Your server makes a token for each signed-in user with your secret key. The SDK asks for a new one when it runs out.

app.get('/vybe-token', requireUser, async (req, res) => {
  const r = await fetch('https://vybemusic.com/api/library/v1/sessions', {
    method: 'POST',
    headers: { Authorization: 'Bearer ' + process.env.VYBE_SECRET_KEY, 'Content-Type': 'application/json' },
    body: JSON.stringify({ user: req.user.id, hours: 1 }),
  });
  res.status(r.status).json(await r.json());   // { token, expires_at }
});

VybeSDK.init({ getToken: () => fetch('/vybe-token').then(r => r.json()) });

Publishable keys and session tokens are limited per listener (120 requests a minute), so one busy user never slows down the rest.

React

export function Music() {
  const [now, setNow] = useState(null);
  useEffect(() => VybeSDK.player.on('trackchange', ({ track }) => setNow(track)), []);
  return (<>
    <vybe-vybes for="songs"></vybe-vybes>
    <vybe-tracks id="songs" vybe="chill"></vybe-tracks>
    {now && <p>Now playing {now.title}</p>}
  </>);
}

Using VYBE music

• Keep the "Music from VYBE" attribution and the artist links the elements show.
• Leave play reporting on. Artists see where they are heard, and that is why they share.
• Do not download, cache or pass on the audio or the media links.
• Pass user (your id for the listener; VYBE stores only a one-way hash) and country when you have them.

The full rules are in the Library Partner Terms and the license in the download.

Errors

Elements show a short message when something is wrong and log the details to the console. In code, calls throw a VybeError with status, code and message: invalid_key, origin_not_allowed (add the website to your key), token_expired, rate_limited, partner_paused, not_found.

Download

VYBE SDK 1.1.0 (23 KB)

Inside: vybe-sdk.js (no dependencies), vybe-sdk.d.ts, a README, examples (a website, a React component and a server that makes session tokens) and the VYBE Partner SDK License. Want to read or make .vybe files in your own product? The format and its tools are open source: vybemusic.com/open.