# Environment Variable Configuration Guide

This guide explains how to configure the KAR Player using environment variables for easy customization without code changes.

## Quick Start

### 1. Copy the example file

```bash
cp .env.example .env.local
```

### 2. Choose a preset or customize

The easiest way is to use one of the built-in presets:

```bash
# Extreme Karaoke (Thai style - alternating highlight)
KAR_PLAYER_THEME=extreme-karaoke
KAR_PLAYER_DISPLAY_MODE=extreme-karaoke

# Traditional Karaoke
KAR_PLAYER_THEME=karaoke
KAR_PLAYER_DISPLAY_MODE=three-line

# Minimal Clean
KAR_PLAYER_THEME=minimal
KAR_PLAYER_DISPLAY_MODE=three-line
```

### 3. Use in your app

```tsx
import { 
  useLyricRenderer, 
  loadDisplayOptionsFromEnv,
  createThemeFromEnv 
} from '@karaplay/kar-player';
import '@karaplay/kar-player/dist/components/styles/index.css';

function KaraokePlayer({ lyrics, currentTime }) {
  // Load configuration from environment
  const envOptions = loadDisplayOptionsFromEnv();
  const envTheme = createThemeFromEnv();

  const { containerRef } = useLyricRenderer(lyrics, currentTime, {
    ...envOptions,
    theme: envTheme,
    // You can still override with custom values
    onLineChange: (index, line) => console.log('Line changed')
  });

  return <div ref={containerRef} />;
}
```

## Built-in Themes

### 1. Extreme Karaoke (extreme-karaoke)

Perfect for Thai karaoke boxes with alternating highlight colors.

**Features:**
- 2 lines displayed at once
- Top line highlights in **blue** (#60a5fa)
- Bottom line highlights in **yellow/gold** (#fbbf24)
- Lines alternate smoothly
- Gradient background with glow effects
- Large, bold fonts

**Best for:** Traditional karaoke experience, Thai language

**Environment variables:**
```bash
KAR_PLAYER_THEME=extreme-karaoke
KAR_PLAYER_DISPLAY_MODE=extreme-karaoke
KAR_PLAYER_FONT_FAMILY="Kanit", "Arial Black", Impact, sans-serif
```

### 2. Karaoke (karaoke)

Traditional karaoke box style with single color highlight.

**Features:**
- 3 lines (prev, current, next)
- Gold (#ffd700) highlight
- Gradient purple background
- Bouncing word animation
- Bold, impactful fonts

**Best for:** Standard karaoke experience

**Environment variables:**
```bash
KAR_PLAYER_THEME=karaoke
KAR_PLAYER_DISPLAY_MODE=three-line
```

### 3. Minimal (minimal)

Clean, subtle, modern design.

**Features:**
- Simple text display
- Blue (#007aff) highlight
- Transparent background
- Subtle animations
- System fonts

**Best for:** Modern apps, background music, study apps

**Environment variables:**
```bash
KAR_PLAYER_THEME=minimal
KAR_PLAYER_DISPLAY_MODE=three-line
```

### 4. Default (default)

Balanced, general-purpose design.

**Features:**
- Clean and simple
- Red (#ff4444) highlight
- Transparent background
- Moderate font sizes
- Smooth transitions

**Best for:** General use, web apps

## Display Modes

### extreme-karaoke

Two lines with alternating highlight - top line (blue) then bottom line (yellow).

**Perfect for:** Traditional Thai/Asian karaoke boxes

```bash
KAR_PLAYER_DISPLAY_MODE=extreme-karaoke
```

### three-line (Default)

Shows previous, current, and next lines.

```bash
KAR_PLAYER_DISPLAY_MODE=three-line
```

### two-line

Shows current and next lines only.

```bash
KAR_PLAYER_DISPLAY_MODE=two-line
```

### single-line

Shows only the current line.

```bash
KAR_PLAYER_DISPLAY_MODE=single-line
```

### full

Shows all lyrics with scroll.

```bash
KAR_PLAYER_DISPLAY_MODE=full
```

## Custom Configuration

### Colors

```bash
# Inactive (unsung) words
KAR_PLAYER_COLOR_INACTIVE=#888888

# Active (currently singing) words
KAR_PLAYER_COLOR_ACTIVE=#ff0000

# Current line text
KAR_PLAYER_COLOR_CURRENT=#ffffff

# Previous line text
KAR_PLAYER_COLOR_PREV=#999999

# Next line text
KAR_PLAYER_COLOR_NEXT=#cccccc

# Background (can use gradients)
KAR_PLAYER_COLOR_BACKGROUND=linear-gradient(135deg, #667eea 0%, #764ba2 100%)
```

### Fonts

```bash
# Font family (CSS font stack)
KAR_PLAYER_FONT_FAMILY="Kanit", "Sarabun", sans-serif

# Font sizes
KAR_PLAYER_FONT_SIZE_CURRENT=3rem
KAR_PLAYER_FONT_SIZE_PREV=2rem
KAR_PLAYER_FONT_SIZE_NEXT=2rem

# Font weights (100-900)
KAR_PLAYER_FONT_WEIGHT_CURRENT=900
KAR_PLAYER_FONT_WEIGHT_PREV=600
KAR_PLAYER_FONT_WEIGHT_NEXT=600
```

### Spacing

```bash
# Line height (unitless or with unit)
KAR_PLAYER_LINE_HEIGHT=1.5

# Word spacing
KAR_PLAYER_WORD_SPACING=0.75rem

# Container padding
KAR_PLAYER_PADDING=4rem 3rem
```

### Animations

```bash
# Transition duration
KAR_PLAYER_TRANSITION_DURATION=0.4s

# Highlight animation duration
KAR_PLAYER_HIGHLIGHT_DURATION=0.3s

# Scroll animation duration
KAR_PLAYER_SCROLL_DURATION=0.5s
```

### Behavior

```bash
# Auto-scroll to current line
KAR_PLAYER_AUTO_SCROLL=true

# Smooth scroll animation
KAR_PLAYER_SMOOTH_SCROLL=true
```

## Recommended Presets

### Thai Karaoke Box

```bash
KAR_PLAYER_DISPLAY_MODE=extreme-karaoke
KAR_PLAYER_THEME=extreme-karaoke
KAR_PLAYER_FONT_FAMILY="Kanit", "Sarabun", "Leelawadee UI", sans-serif
KAR_PLAYER_FONT_SIZE_CURRENT=3rem
KAR_PLAYER_FONT_WEIGHT_CURRENT=900
```

### YouTube Music Video Style

```bash
KAR_PLAYER_DISPLAY_MODE=single-line
KAR_PLAYER_THEME=minimal
KAR_PLAYER_FONT_FAMILY="YouTube Sans", "Roboto", sans-serif
KAR_PLAYER_COLOR_ACTIVE=#ff0000
KAR_PLAYER_COLOR_BACKGROUND=transparent
```

### Spotify Lyrics Style

```bash
KAR_PLAYER_DISPLAY_MODE=full
KAR_PLAYER_THEME=minimal
KAR_PLAYER_FONT_FAMILY="Circular", -apple-system, sans-serif
KAR_PLAYER_COLOR_ACTIVE=#1db954
KAR_PLAYER_FONT_SIZE_CURRENT=3rem
```

### Apple Music Style

```bash
KAR_PLAYER_DISPLAY_MODE=three-line
KAR_PLAYER_THEME=minimal
KAR_PLAYER_FONT_FAMILY="SF Pro Display", -apple-system, sans-serif
KAR_PLAYER_COLOR_ACTIVE=#007aff
KAR_PLAYER_FONT_SIZE_CURRENT=2.5rem
```

## Advanced Usage

### Programmatic Configuration

```typescript
import { 
  loadEnvConfig,
  envConfigToTheme,
  envConfigToDisplayOptions,
  mergeWithEnvConfig 
} from '@karaplay/kar-player';

// Load all env config
const envConfig = loadEnvConfig();

// Convert to theme
const customTheme = envConfigToTheme(envConfig, 'my-custom-theme');

// Convert to display options
const displayOptions = envConfigToDisplayOptions(envConfig);

// Merge with user config (user config takes precedence)
const finalOptions = mergeWithEnvConfig({
  displayMode: 'three-line', // This overrides env
  highlightMode: 'word'
});
```

### Dynamic Theme Switching

```tsx
import { useLyricRenderer, createThemeFromEnv } from '@karaplay/kar-player';

function KaraokePlayer() {
  const [themeName, setThemeName] = useState('extreme-karaoke');
  
  // Create theme from env or use built-in
  const theme = themeName === 'custom' 
    ? createThemeFromEnv('custom')
    : themeName;

  const { containerRef } = useLyricRenderer(lyrics, currentTime, {
    theme,
    displayMode: 'extreme-karaoke'
  });

  return (
    <div>
      <select onChange={(e) => setThemeName(e.target.value)}>
        <option value="extreme-karaoke">Extreme Karaoke</option>
        <option value="karaoke">Karaoke</option>
        <option value="minimal">Minimal</option>
        <option value="custom">Custom (from .env)</option>
      </select>
      <div ref={containerRef} />
    </div>
  );
}
```

## Troubleshooting

### Environment variables not working?

1. **Next.js:** Make sure variables start with `NEXT_PUBLIC_`
   ```bash
   NEXT_PUBLIC_KAR_PLAYER_THEME=extreme-karaoke
   ```

2. **Restart dev server** after changing `.env.local`

3. **Check variable names** - they are case-sensitive

4. **Import CSS:**
   ```tsx
   import '@karaplay/kar-player/dist/components/styles/index.css';
   ```

### Colors not applying?

Make sure to use valid CSS color values:
- Hex: `#ff0000`
- RGB: `rgb(255, 0, 0)`
- RGBA: `rgba(255, 0, 0, 0.8)`
- Named: `red`
- Gradient: `linear-gradient(135deg, #667eea 0%, #764ba2 100%)`

### Fonts not working?

1. **Import Google Fonts** in your app:
   ```tsx
   // In layout.tsx or _app.tsx
   import { Kanit } from 'next/font/google';
   const kanit = Kanit({ weight: ['400', '600', '900'], subsets: ['thai'] });
   ```

2. **Use CSS font stack** with fallbacks:
   ```bash
   KAR_PLAYER_FONT_FAMILY="Kanit", "Sarabun", "Arial", sans-serif
   ```

## Examples

See `EXAMPLES.md` for complete code examples using environment configuration.