Playing Audio Pronunciations

A core feature of any digital dictionary is the ability to hear how a word is pronounced. The Shobdo API provides high-quality audio pronunciations for millions of words, spoken by native speakers in various regional accents.

Locating the Audio URL

When you fetch a dictionary entry using the /search or /entries endpoint, the response contains a phonetics array. If an audio file is available for a phonetic pronunciation, it will include an audioUrl pointing directly to our CDN.

{
  "word": "dictionary",
  "phonetics": [
    {
      "text": "/ˈdɪk.ʃən.ər.i/",
      "audioUrl": "https://api.shobdo.me/api/v1/api/audio/en/dictionary"
    },
    {
      "text": "/ˈdɪk.ʃən.ri/",
      "audioUrl": "https://api.shobdo.me/api/v1/api/audio/en/dictionary-uk"
    }
  ]
}

Playing Audio in the Browser

Because the audioUrl points to a publicly accessible MP3 or OGG file, playing it in a web browser is incredibly straightforward using the native HTML5 <audio> element.

Option 1: Native Audio Controls

If you want the browser to handle the UI for the audio player, simply pass the URL into the src attribute of an <audio> tag:

<!-- Using the audioUrl from the Entry response -->
<audio controls>
  <source src="https://api.shobdo.me/api/v1/api/audio/en/dictionary" />
  Your browser does not support the audio element.
</audio>

Option 2: Custom UI (JavaScript)

Most modern dictionary applications use a custom speaker icon (🔊) that plays the audio when clicked. You can achieve this using the JavaScript Audio constructor:

// Assume `entry` is the response from the Shobdo API
const phoneticsWithAudio = entry.phonetics.filter(p => p.audioUrl !== "");
 
if (phoneticsWithAudio.length > 0) {
  // Grab the first available audio pronunciation
  const audioUrl = phoneticsWithAudio[0].audioUrl;
  
  // Create an audio instance
  const audio = new Audio(audioUrl);
 
  // Attach to a button click
  document.getElementById("play-btn").addEventListener("click", () => {
    audio.play().catch(error => {
      console.error("Audio playback failed:", error);
    });
  });
}

Advanced: The Audio Endpoint

While the audioUrl provided in the Entry response is the easiest way to access audio, you can also fetch audio directly using the /api/v1/api/audio/{source}/{lexid} endpoint.

This is useful if you just want to grab the pronunciation of a word without fetching its definitions!

curl -X GET "https://api.shobdo.me/api/v1/api/audio/en/dictionary" \
  -H "Authorization: Bearer YOUR_API_KEY"

This endpoint returns raw binary audio data (e.g., audio/mpeg). You can pipe this output directly into an audio streaming service or save it to disk.