# Karaoke Language Learning Dapp

[![en](https://img.shields.io/badge/lang-en-blue.svg)](https://github.com/technohippies/karaoke-dapp/blob/main/README.md)
[![zh](https://img.shields.io/badge/lang-zh-red.svg)](https://github.com/technohippies/karaoke-dapp/blob/main/README.zh.md)

A decentralized karaoke application that combines language learning with blockchain technology, using Lit Protocol for secure content encryption.

## 🎤 Features

- **Multi-language Support**: Available in English, Chinese (中文), Uyghur (ئۇيغۇرچە), and Tibetan (བོད་སྐད)
- **Spaced Repetition System (SRS)**: Learn lyrics efficiently using the FSRS algorithm
- **Encrypted Content**: Translations protected via Lit Protocol
- **Web3 Authentication**: Connect with popular wallets including MetaMask, Coinbase, and JoyID
- **Voice & Song Credits**: Token-based access system
- **AI-Powered Feedback**: Real-time pronunciation scoring
- **Offline-First**: Local data persistence with IndexedDB

## 🚀 Quick Start

### Prerequisites
- Node.js 18+ or Bun
- Base Mainnet ETH for transactions
- USDC on Base Mainnet for purchasing credits

### Installation

```bash
# Clone the repository
git clone https://github.com/technohippies/karaoke-dapp.git
cd karaoke-dapp

# Install dependencies
bun install

# Set up environment variables
cd apps/web
cp .env.example .env
# Edit .env with your configuration

# Start development server
bun dev
```

For local development, create `.env.local` to override any settings.

## 📁 Project Structure

```
karaoke-dapp/
├── apps/
│   └── web/                 # React frontend application
│       ├── src/
│       │   ├── components/  # UI components
│       │   ├── pages/       # Route pages
│       │   ├── services/    # Business logic
│       │   ├── hooks/       # Custom React hooks
│       │   └── i18n/        # Translations
│       └── public/
├── contracts/               # Smart contracts
│   ├── src/                # Solidity contracts
│   └── script/             # Deployment scripts
├── lit-actions/            # Lit Protocol serverless functions
├── scripts/                # Utility scripts
├── tableland/              # Tableland database management
```

## 🏗️ Architecture

### Smart Contracts

**KaraokeSchool** (`0xbfdAbCa93e738E343351D629a541f32636d39ac3` (v4karaoke.deployd.base.eth
) on Base Mainnet)
- Manages voice and song credits
- Handles song unlocking mechanism
- Escrows credits during karaoke sessions
- Verifies PKP signatures for scoring

### Lit Protocol Integration

- **Content Encryption**: Translations encrypted via Lit Protocol
- **Access Control**: Only users who unlocked songs can decrypt content
- **Lit Actions**: 
  - Karaoke Scorer - Contains embedded API keys for Deepgram (STT) and OpenRouter (LLM)
  - Exercise - "Say It Back": Single line STT grading

### Database

- **IndexedDB**: Local storage for offline functionality
- **Tableland**: Decentralized SQL database for song metadata
- **IPFS (Pinata)**: Encrypted content storage

## 🛠️ Development

### Production Build

```bash
# Build frontend
cd apps/web
bun run build

# The app is deployed on Base Mainnet
# Current deployment:
# - Contract: 0xbfdAbCa93e738E343351D629a541f32636d39ac3 (v4karaokeschool.technohippies.base.eth)
# - Splits: 0x90840E8cfbeEB3adC85cb665A5b9CeB942150f88
# - Network: Base Mainnet (Chain ID: 8453)
# - Tableland: karaoke_songs_8453_8453_25
```

## 📄 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPLv3) - see the LICENSE file for details.

## 📚 Repository Access

This project is available on multiple platforms for redundancy and censorship resistance:

### Primary Repository
- **GitHub**: https://github.com/technohippies/karaoke-dapp.git

### Decentralized Mirrors
- **Radicle**: https://app.radicle.xyz/nodes/rosa.radicle.xyz/rad:zjAPSYMsctUsESkgc9XqTgcstWUH
- **Clone via Radicle**: `rad:zjAPSYMsctUsESkgc9XqTgcstWUH`

The Radicle repository serves as a decentralized, censorship-resistant mirror. Updates are automatically synced from GitHub with a slight delay. If the repository is removed from centralized platforms for any reason, or if access is restricted in your region, the full codebase remains permanently accessible through Radicle's peer-to-peer network.

## ⚖️ Legal Notice and Copyright Compliance

- **Lyrics Content**: All copyrighted lyrics are dynamically loaded from LRCLIB's API. We do not host, store, or distribute any copyrighted lyrical content on our servers or in this repository.