@liaplus/voice-navigation-ai

v1.0.1

Published

8 months ago

AI-powered voice navigation component for Next.js with OpenAI integration

Downloads

0High
0Medium
0Low

shaileshlia

amitliaplus

voice navigation ai accessibility speech-recognition openai nextjs react voice-commands voice-assistant

🎤 Voice Navigation AI

An AI-powered voice navigation component for Next.js applications with OpenAI integration. Provides hands-free website navigation with speech recognition and natural language processing.

✨ Features

🎯 AI-Powered Commands - Natural language understanding with OpenAI
🗣️ Speech Recognition - Built-in Web Speech API support
📱 Fully Responsive - Optimized for mobile, tablet, and desktop
⚡ Easy Integration - Drop-in component for Next.js 13+
🎨 Customizable - Extend with custom commands and styling
♿ Accessible - WCAG compliant with ARIA labels
🌐 Multi-Language - Support for multiple languages (configurable)
🔧 Type Safe - Full TypeScript support

📦 Installation

npm install @liaplus/voice-navigation-ai

Peer Dependencies

Make sure you have the required peer dependencies installed:

npm install next react react-dom

Additional Dependencies

The package also requires these dependencies (automatically installed):

npm install lucide-react class-variance-authority clsx tailwind-merge

🚀 Quick Start

1. Add the Component to Your Layout

// app/layout.tsx
import { VoiceNavigationAdvanced } from '@liaplus/voice-navigation-ai'

export default function RootLayout({ children }) {
  return (
    <html lang="en">
      <body>
        {children}
        <VoiceNavigationAdvanced />
      </body>
    </html>
  )
}

2. Create the API Route

Create a new file at app/api/voice-command/route.ts:

// app/api/voice-command/route.ts
export { POST } from '@liaplus/voice-navigation-ai/api'

3. Set Environment Variable

Add your OpenAI API key to .env.local:

OPENAI_API_KEY=sk-your-openai-api-key-here

That's it! 🎉 Your voice navigation is now active.

📖 Detailed Setup

Custom API Handler

If you need more control over the API handler:

// app/api/voice-command/route.ts
import { createVoiceCommandHandler } from '@liaplus/voice-navigation-ai/api'

export const POST = createVoiceCommandHandler({
  openaiApiKey: process.env.OPENAI_API_KEY,
  model: 'gpt-4o-mini', // or 'gpt-4'
  systemPrompt: `Your custom system prompt here...`
})

Custom Commands

Extend the default commands with your own:

import { VoiceNavigationAdvanced } from '@liaplus/voice-navigation-ai'

export default function Layout({ children }) {
  return (
    <>
      {children}
      <VoiceNavigationAdvanced
        customCommands={{
          'dashboard': {
            keywords: ['dashboard', 'go to dashboard', 'show dashboard'],
            action: '/dashboard', // String path for navigation
            description: 'Go to dashboard',
            category: 'navigation'
          },
          'logout': {
            keywords: ['logout', 'sign out', 'log out'],
            action: () => {
              // Custom function
              signOut()
            },
            description: 'Sign out',
            category: 'system'
          }
        }}
      />
    </>
  )
}

Component Props

interface VoiceNavigationProps {
  /**
   * Custom command mappings to extend or override default commands
   */
  customCommands?: Record<string, {
    keywords: string[]
    action: string | (() => void)
    description: string
    category: 'navigation' | 'scrolling' | 'content' | 'system' | 'products' | 'resources' | 'solutions' | 'info'
  }>
  
  /**
   * API endpoint for AI-powered voice command processing
   * @default '/api/voice-command'
   */
  apiEndpoint?: string
  
  /**
   * Enable AI mode by default
   * @default false
   */
  defaultAIMode?: boolean
  
  /**
   * Enable voice feedback by default
   * @default true
   */
  defaultVoiceFeedback?: boolean
  
  /**
   * Show commands list by default
   * @default true
   */
  defaultShowCommands?: boolean
}

🎮 Default Commands

📜 Scrolling

"scroll up" / "move up" / "go up"
"scroll down" / "move down" / "go down"
"go to top" / "top of page"
"go to bottom" / "bottom of page"
"go to middle" / "center"

🧭 Navigation

"go home" / "home page"
"show products" / "products page"
"show pricing" / "pricing page"
"about us" / "about page"
"contact us" / "contact page"
"solutions page"

🔧 System

"go back" / "back"
"print page" / "print"
"hide commands" / "show commands"
"scroll commands up" / "scroll commands down"

📖 Content

"read page" / "read content"
"stop reading" / "stop"

ℹ️ Info

"help" / "show commands"

🎨 Styling

The component uses Tailwind CSS classes. Make sure your tailwind.config.js includes the package:

// tailwind.config.js
module.exports = {
  content: [
    './app/**/*.{js,ts,jsx,tsx,mdx}',
    './components/**/*.{js,ts,jsx,tsx,mdx}',
    './node_modules/@liaplus/voice-navigation-ai/**/*.{js,ts,jsx,tsx}',
  ],
  // ... rest of your config
}

Custom Styling

You can customize the appearance by wrapping the component and applying custom CSS classes or by modifying your Tailwind theme.

🔐 Environment Variables

| Variable | Required | Description | |----------|----------|-------------| | OPENAI_API_KEY | Yes (for AI mode) | Your OpenAI API key |

Getting an OpenAI API Key

Go to OpenAI Platform
Sign up or log in
Navigate to API Keys section
Create a new API key
Add it to your .env.local file

🌐 Browser Support

✅ Chrome (Desktop & Mobile)
✅ Edge (Desktop & Mobile)
✅ Safari (Desktop & Mobile)
⚠️ Firefox (Desktop only - limited speech recognition support)

The Web Speech API is required for voice recognition. The component will automatically hide itself if speech recognition is not supported.

📱 Responsive Design

The component is fully responsive with:

Mobile: Bottom sheet layout, larger touch targets
Tablet: Optimized positioning and sizing
Desktop: Traditional floating UI with compact controls

🛠️ Advanced Usage

Without AI Mode (Keyword Matching Only)

You can use the component without OpenAI by simply not setting the OPENAI_API_KEY or by keeping AI mode disabled:

<VoiceNavigationAdvanced
  defaultAIMode={false}
/>

Custom API Endpoint

If you're hosting the API route at a different path:

<VoiceNavigationAdvanced
  apiEndpoint="/api/custom/voice"
/>

Programmatic Control

Access the component via ref for programmatic control (advanced):

const voiceNavRef = useRef()

// Toggle listening programmatically
voiceNavRef.current?.toggleListening()

🧪 Testing

The component includes built-in error handling for:

Microphone permission denied
Network failures
API errors
Unsupported browsers

📄 License

MIT © LiaPlus

🤝 Contributing

Contributions are welcome! Please feel free to submit a Pull Request.

Fork the repository
Create your feature branch (git checkout -b feature/AmazingFeature)
Commit your changes (git commit -m 'Add some AmazingFeature')
Push to the branch (git push origin feature/AmazingFeature)
Open a Pull Request

📞 Support

📧 Email: [email protected]
🐛 Issues: GitHub Issues
📖 Documentation: Full Documentation

🙏 Acknowledgments

Built with Next.js
Powered by OpenAI
Icons by Lucide
UI components inspired by shadcn/ui

Made with ❤️ by LiaPlus