# Text-Only Mode - Custom Background Guide

This guide shows you how to use **text-only mode** to display lyrics with custom backgrounds.

## Why Text-Only Mode?

- 🎨 **Full creative control** - Use your own backgrounds
- 🖼️ **Video backgrounds** - Perfect for video overlays
- 📹 **Green screen** - For video editing and streaming
- 🎥 **OBS Studio** - Great for live streaming
- 🌈 **Animated backgrounds** - CSS animations, videos, etc.

---

## Method 1: useLyricText() - Full Control 🎯

**Best for:** Maximum flexibility and control

```tsx
import { useLyricText } from '@karaplay/kar-player';

function CustomBackgroundLyrics({ lyrics, currentTime }) {
  const { textElements } = useLyricText(lyrics, currentTime, {
    displayMode: 'extreme-karaoke',
    activeColor: '#ffd700',           // Gold for highlighted words
    inactiveColor: '#ffffff',         // White for inactive
    currentFontSize: '3rem',
    highlightTextShadow: '0 0 20px rgba(255, 215, 0, 0.8)',
    activeWordStyle: {
      fontWeight: 900,
      transform: 'scale(1.1)'
    }
  });

  return (
    <div style={{
      backgroundImage: 'url(/my-custom-bg.jpg)',
      backgroundSize: 'cover',
      padding: '4rem',
      minHeight: '400px',
      display: 'flex',
      flexDirection: 'column',
      alignItems: 'center',
      justifyContent: 'center'
    }}>
      {textElements.map((line, i) => (
        <div key={i} style={line.style}>
          {line.words.map((word, j) => (
            <span key={j} style={word.style} className={word.className}>
              {word.text}
            </span>
          ))}
        </div>
      ))}
    </div>
  );
}
```

---

## Method 2: textOnly Option - Quick & Easy ⚡

**Best for:** Quick implementation with existing hooks

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

function QuickCustomBG({ lyrics, currentTime }) {
  const { containerRef } = useLyricRenderer(lyrics, currentTime, {
    textOnly: true,  // ✅ No container styling!
    displayMode: 'extreme-karaoke',
    theme: 'extreme-karaoke'
  });

  return (
    <div style={{
      backgroundImage: 'url(/my-bg.jpg)',
      backgroundSize: 'cover',
      padding: '3rem'
    }}>
      <div ref={containerRef} />
    </div>
  );
}
```

---

## Method 3: Disable Background Only 🎨

**Best for:** Keep layout, change background only

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

function SemiCustom({ lyrics, currentTime }) {
  const { containerRef } = useLyricRenderer(lyrics, currentTime, {
    disableBackground: true,  // ✅ Remove background but keep layout
    theme: 'karaoke'
  });

  return (
    <div style={{ background: 'linear-gradient(...)' }}>
      <div ref={containerRef} />
    </div>
  );
}
```

---

## Examples

### Example 1: Video Background

```tsx
function VideoBackgroundLyrics({ lyrics, currentTime }) {
  const { textElements } = useLyricText(lyrics, currentTime, {
    displayMode: 'extreme-karaoke',
    activeColor: '#ffd700',
    inactiveColor: '#ffffff',
    currentFontSize: '3.5rem',
    currentFontWeight: 900,
    highlightTextShadow: '0 0 30px rgba(255, 215, 0, 1), 0 4px 8px rgba(0, 0, 0, 0.8)'
  });

  return (
    <div style={{ position: 'relative', width: '100%', height: '100vh' }}>
      {/* Video background */}
      <video 
        autoPlay 
        loop 
        muted 
        style={{
          position: 'absolute',
          width: '100%',
          height: '100%',
          objectFit: 'cover',
          zIndex: -1
        }}
      >
        <source src="/background.mp4" type="video/mp4" />
      </video>

      {/* Lyrics overlay */}
      <div style={{
        position: 'absolute',
        top: '50%',
        left: '50%',
        transform: 'translate(-50%, -50%)',
        textAlign: 'center',
        width: '80%'
      }}>
        {textElements.map((line, i) => (
          <div key={i} style={line.style}>
            {line.words.map((word, j) => (
              <span key={j} style={word.style}>
                {word.text}
              </span>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Example 2: Image Background with Blur

```tsx
function BlurBackgroundLyrics({ lyrics, currentTime, bgImage }) {
  const { containerRef } = useLyricRenderer(lyrics, currentTime, {
    textOnly: true,
    displayMode: 'extreme-karaoke'
  });

  return (
    <div style={{
      position: 'relative',
      backgroundImage: `url(${bgImage})`,
      backgroundSize: 'cover',
      backgroundPosition: 'center',
      minHeight: '400px'
    }}>
      {/* Blur overlay */}
      <div style={{
        position: 'absolute',
        inset: 0,
        backdropFilter: 'blur(20px)',
        backgroundColor: 'rgba(0, 0, 0, 0.5)'
      }} />

      {/* Lyrics */}
      <div style={{ position: 'relative', padding: '3rem' }}>
        <div ref={containerRef} />
      </div>
    </div>
  );
}
```

### Example 3: Gradient Animated Background

```tsx
function AnimatedGradientLyrics({ lyrics, currentTime }) {
  const { textElements } = useLyricText(lyrics, currentTime, {
    displayMode: 'extreme-karaoke',
    activeColor: '#ffffff',
    inactiveColor: 'rgba(255, 255, 255, 0.6)',
    currentFontSize: '3rem',
    highlightTextShadow: '0 0 20px rgba(255, 255, 255, 0.8)'
  });

  return (
    <div style={{
      background: 'linear-gradient(45deg, #667eea, #764ba2, #f093fb, #4facfe)',
      backgroundSize: '400% 400%',
      animation: 'gradientShift 15s ease infinite',
      padding: '4rem',
      minHeight: '400px'
    }}>
      <style>{`
        @keyframes gradientShift {
          0% { background-position: 0% 50%; }
          50% { background-position: 100% 50%; }
          100% { background-position: 0% 50%; }
        }
      `}</style>

      <div style={{
        display: 'flex',
        flexDirection: 'column',
        alignItems: 'center',
        gap: '2rem'
      }}>
        {textElements.map((line, i) => (
          <div key={i} style={line.style}>
            {line.words.map((word, j) => (
              <span key={j} style={word.style}>
                {word.text}
              </span>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Example 4: Green Screen for OBS/Streaming

```tsx
function GreenScreenLyrics({ lyrics, currentTime }) {
  const { textElements } = useLyricText(lyrics, currentTime, {
    displayMode: 'extreme-karaoke',
    activeColor: '#ffd700',
    inactiveColor: '#ffffff',
    currentFontSize: '4rem',
    currentFontWeight: 900,
    highlightTextShadow: '0 4px 8px rgba(0, 0, 0, 1), 0 0 30px rgba(255, 215, 0, 0.8)'
  });

  return (
    <div style={{
      backgroundColor: '#00ff00', // Chroma key green
      width: '1920px',
      height: '1080px',
      display: 'flex',
      alignItems: 'center',
      justifyContent: 'center'
    }}>
      <div style={{ textAlign: 'center' }}>
        {textElements.map((line, i) => (
          <div key={i} style={{
            ...line.style,
            marginBottom: '2rem'
          }}>
            {line.words.map((word, j) => (
              <span 
                key={j} 
                style={{
                  ...word.style,
                  // Extra shadow for better keying
                  textShadow: word.highlighted 
                    ? '0 4px 8px rgba(0, 0, 0, 1), 0 0 30px rgba(255, 215, 0, 0.8)'
                    : '0 4px 8px rgba(0, 0, 0, 0.8)'
                }}
              >
                {word.text}
              </span>
            ))}
          </div>
        ))}
      </div>
    </div>
  );
}
```

### Example 5: Using Environment Variables

```tsx
// .env.local
NEXT_PUBLIC_KAR_PLAYER_DISPLAY_MODE=extreme-karaoke
NEXT_PUBLIC_KAR_PLAYER_COLOR_ACTIVE=#ffd700
NEXT_PUBLIC_KAR_PLAYER_COLOR_INACTIVE=#ffffff
NEXT_PUBLIC_KAR_PLAYER_FONT_SIZE_CURRENT=3rem

// Component
import { useLyricText, loadDisplayOptionsFromEnv } from '@karaplay/kar-player';

function EnvConfiguredLyrics({ lyrics, currentTime, bgImage }) {
  const envOptions = loadDisplayOptionsFromEnv();
  
  const { textElements } = useLyricText(lyrics, currentTime, {
    ...envOptions,
    // Add custom colors
    activeColor: process.env.NEXT_PUBLIC_KAR_PLAYER_COLOR_ACTIVE,
    inactiveColor: process.env.NEXT_PUBLIC_KAR_PLAYER_COLOR_INACTIVE
  });

  return (
    <div style={{ backgroundImage: `url(${bgImage})` }}>
      {textElements.map((line, i) => (
        <div key={i} style={line.style}>
          {line.words.map((word, j) => (
            <span key={j} style={word.style}>
              {word.text}
            </span>
          ))}
        </div>
      ))}
    </div>
  );
}
```

---

## Customization Options

### Colors

```tsx
{
  activeColor: '#ff0000',              // Highlighted word color
  inactiveColor: '#666666',            // Non-highlighted word color
  currentLineColor: '#ffffff',         // Current line color
  prevLineColor: '#999999',            // Previous line color
  nextLineColor: '#cccccc'             // Next line color
}
```

### Fonts

```tsx
{
  currentFontSize: '3rem',             // Current line font size
  prevFontSize: '2rem',                // Previous line font size
  nextFontSize: '2rem',                // Next line font size
  currentFontWeight: 900,              // Current line font weight
  prevFontWeight: 600,                 // Previous line font weight
  nextFontWeight: 600                  // Next line font weight
}
```

### Effects

```tsx
{
  highlightTextShadow: '0 0 20px rgba(255, 0, 0, 0.8)',  // Text shadow for highlights
  activeWordStyle: {                   // Custom CSS for active words
    transform: 'scale(1.1)',
    fontWeight: 900
  },
  inactiveWordStyle: {                 // Custom CSS for inactive words
    opacity: 0.8
  }
}
```

---

## Comparison

| Feature | Normal Mode | Text-Only Mode |
|---------|-------------|----------------|
| Container BG | ✅ Included | ❌ None |
| Layout | ✅ Pre-styled | ⚠️ Your control |
| Text Highlight | ✅ Yes | ✅ Yes |
| Word Timing | ✅ Yes | ✅ Yes |
| Custom BG | ⚠️ Override | ✅ Full control |
| Inline Styles | ❌ No | ✅ Yes |

---

## Tips

### 1. Use Strong Text Shadows

For better readability on any background:

```tsx
highlightTextShadow: '0 4px 8px rgba(0, 0, 0, 0.9), 0 0 20px rgba(255, 215, 0, 0.8)'
```

### 2. Contrast is Key

Make sure text color contrasts well with your background:

```tsx
// Dark background
activeColor: '#ffd700'
inactiveColor: '#ffffff'

// Light background  
activeColor: '#ff0000'
inactiveColor: '#333333'
```

### 3. Responsive Font Sizes

Use viewport units for responsive text:

```tsx
currentFontSize: '5vw'  // Scales with viewport width
```

### 4. Position Absolutely

For overlays on videos:

```tsx
<div style={{ position: 'relative' }}>
  <video ... />
  <div style={{
    position: 'absolute',
    top: '60%',
    left: '50%',
    transform: 'translate(-50%, -50%)',
    width: '80%',
    textAlign: 'center'
  }}>
    {textElements.map(...)}
  </div>
</div>
```

---

## Environment Variables for Text-Only

```bash
# .env.local

# Text-only specific colors
NEXT_PUBLIC_KAR_PLAYER_COLOR_ACTIVE=#ffd700
NEXT_PUBLIC_KAR_PLAYER_COLOR_INACTIVE=#ffffff
NEXT_PUBLIC_KAR_PLAYER_COLOR_CURRENT=#ffffff

# Font settings
NEXT_PUBLIC_KAR_PLAYER_FONT_SIZE_CURRENT=3.5rem
NEXT_PUBLIC_KAR_PLAYER_FONT_WEIGHT_CURRENT=900
NEXT_PUBLIC_KAR_PLAYER_FONT_FAMILY="Kanit", "Arial Black", sans-serif
```

Then use:

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

const envTheme = createThemeFromEnv();
const { textElements } = useLyricText(lyrics, currentTime, {
  activeColor: envTheme.colors.active,
  inactiveColor: envTheme.colors.inactive,
  currentFontSize: envTheme.fonts?.size.current
});
```

---

## Complete Examples

See `EXAMPLES.md` for more complete implementations!