Nuxt Content Narrator

A Nuxt layer that provides text-to-speech narration capabilities for Nuxt Content pages.

Watch the video with audio on YouTube

Quick Start

1. Install the layer and extend it

npm i nuxt-content-narrator

// nuxt.config.ts
extends: ["nuxt-content-narrator"],

2. Get your ElevanLabs API key and set as an environment variable

   NUXT_ELEVENLABS_API_KEY=sk_xxx

3. Add the NcNarrator components to your content pages

<script setup lang="ts">
  const route = useRoute();

  const { data: story } = await useAsyncData(() =>
    queryCollection("stories")
      .path(route.path.toString() ?? "")
      .first()
  );
</script>

<template>
  <article class="prose prose-lg mx-auto">
    <NcNarratorService
      v-if="story"
      :collection-item="story"
      voiceId="FGY2WhTYpPnrIDTdsKH5"
    >
      <NcNarratorPlayer progressClass="bg-gray-900" />
      <NcNarratorDevTools />
      <NcNarratorFollowAlongRenderer
        highlightClass="bg-gray-900"
        highlightTextClass="text-white"
      />
    </NcNarratorService>
  </article>
</template>

Components Overview

1. NcNarratorService

The core service component that manages the text-to-speech functionality and state.

Props:

• collectionItem: (Required) A Nuxt Content page collection item that includes the rawbody property (read more about rawbody here)
• voiceId: (Optional) The ID of the ElevenLabs voice to use for narration (Visit https://elevenlabs.io/app/voice-lab to browse all Elevan labs voices, click "View" button, and get the voiceId from the url )

Features:

• Manages audio playback state
• Handles audio generation through ElevenLabs API

2. NcNarratorPlayer

A customizable audio player component that provides playback controls.

Props:

• progressClass: (Optional) CSS class for the progress bar (default: "bg-slate-900")

Features:

• Play/pause controls
• Progress bar with current time and duration
• Slot-based API for custom player UI

Customize with Default Slot

<NcNarratorPlayer
  v-slot="{ 
    play, // function to play the audio
    pause, // function to pause the audio
    toggle, // function to toggle the audio
    playing, // boolean to check if the audio is playing
    currentTime, // number to get the current time of the audio
    duration, // number to get the duration of the audio
    percentComplete // number to get the percent complete of the audio
  }"
>
  <!-- Your custom player UI -->
</NcNarratorPlayer>

3. NcNarratorFollowAlongRenderer

An optional component that renders text with synchronized highlighting during audio playback. If you don't need synchronized highlighting, you can use the regular Nuxt Content component.

Props:

• highlightClass: (Optional) CSS class for the highlight background (default: "bg-slate-900")
• highlightTextClass: (Optional) CSS class for the highlighted text (default: "text-white")

Features:

• Word-by-word text highlighting synchronized with audio
• Handles complex HTML content
• Preserves original markup structure
• Smart handling of code blocks and special tags

4. NcNarratorDevTools

Development tools component for audio generation in development.

<!-- 
 Only visible in development mode 
 Displays a button to generate audio for the current page
 -->
<NcNarratorDevTools />

Usage

1. Wrap your content with the NcNarratorService:

<template>
  <NcNarratorService :collection-item="page">
    <!-- Your content and other narrator components -->
  </NcNarratorService>
</template>

2. Add the player component:

<template>
  <NcNarratorService :collection-item="page">
    <NcNarratorPlayer />
    <!-- Your content -->
  </NcNarratorService>
</template>

3. Use the follow-along renderer for synchronized text highlighting:

<template>
  <NcNarratorService :collection-item="page">
    <NcNarratorPlayer />
    <NcNarratorFollowAlongRenderer />

    <!-- 
     or if you only need the audio and not the highlighting use the regular
    Nuxt Content <ContentRenderer/> copmonent
    -->
  </NcNarratorService>
</template>

Requirements

• Nuxt Content module
• ElevenLabs API Key

Styling

The components come with minimal default styling and can be customized using the following:

• Custom CSS classes through props
• Tailwind CSS

Development

To help contribute to the project, you can clone the repo and install the layer by pointing your extends to the local path from another Nuxt project.

// nuxt.config.ts
extends: ["../../nuxt-content-narrator"],

Deploying to Production

Just like your content, the audio is stored in the github repo. It is generated with the button in the NcNarratorDevTools component and stored in the audio folder.