# @alper/video-player - Kullanım Kılavuzu

Modern, özellik zengin React video player kütüphanesi. HLS streaming, altyazılar, klavye kısayolları, dokunmatik hareketler ve daha fazlasını destekler.

---

## 🚀 Temel Kullanım

### Minimum Örnek

```tsx
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function App() {
  return (
    <VideoPlayer
      src="https://example.com/video.mp4"
    />
  );
}
```

### Özelliklerle Birlikte

```tsx
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function App() {
  return (
    <VideoPlayer
      src="https://example.com/video.mp4"
      poster="https://example.com/poster.jpg"
      autoplay={false}
      loop={false}
      muted={false}
      controls={true}
      keyboardShortcuts={true}
      pictureInPicture={true}
      className="my-video-player"
      onPlay={() => console.log('Video başladı!')}
      onPause={() => console.log('Video durdu!')}
      onTimeUpdate={(time) => console.log('Zaman:', time)}
    />
  );
}
```

---

## 🎨 Tema Özelleştirme

```tsx
import { VideoPlayer, PlayerTheme } from '@alper/video-player';
import '@alper/video-player/styles.css';

const myTheme: PlayerTheme = {
  primaryColor: '#3b82f6',    // Ana buton rengi
  accentColor: '#2563eb',     // Hover rengi
  backgroundColor: '#1f2937', // Arka plan
  textColor: '#f9fafb',       // Metin rengi
};

function App() {
  return (
    <VideoPlayer
      src="/video.mp4"
      theme={myTheme}
    />
  );
}
```

---

## 📺 HLS Streaming Desteği

```tsx
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function StreamingVideo() {
  return (
    <VideoPlayer
      src="https://example.com/stream/master.m3u8"
      poster="/poster.jpg"
    />
  );
}
```

**Not:** HLS desteği için `hls.js` otomatik olarak yüklenir (optional dependency).

---

## 📝 Altyazı Desteği

### VTT veya SRT Formatında

```tsx
import { VideoPlayer, SubtitleTrack } from '@alper/video-player';
import '@alper/video-player/styles.css';

const subtitles: SubtitleTrack[] = [
  {
    label: 'Türkçe',
    src: '/subtitles/turkish.vtt',
    srcLang: 'tr',
  },
  {
    label: 'English',
    src: '/subtitles/english.vtt',
    srcLang: 'en',
  },
  {
    label: 'Español',
    src: '/subtitles/spanish.srt',
    srcLang: 'es',
  },
];

function VideoWithSubtitles() {
  return (
    <VideoPlayer
      src="/video.mp4"
      subtitles={subtitles}
    />
  );
}
```

**Desteklenen formatlar:** VTT, SRT

---

## ⌨️ Klavye Kısayolları

Varsayılan olarak aktif. Devre dışı bırakmak için `keyboardShortcuts={false}` kullanın.

| Tuş | Eylem |
|-----|-------|
| `Space` | Oynat/Duraklat |
| `←` | 5 saniye geri |
| `→` | 5 saniye ileri |
| `↑` | Sesi artır (%5) |
| `↓` | Sesi azalt (%5) |
| `M` | Sesi kapat/aç |
| `F` | Tam ekran |
| `P` | Picture-in-Picture |
| `0-9` | Videonun %0-%90'ına git |

---

## 👆 Dokunmatik Hareketler

Mobil cihazlarda otomatik olarak aktiftir:

- **Tek dokunma:** Kontrolleri göster/gizle
- **Çift dokunma:** Oynat/Duraklat
- **Sağa kaydır:** 10 saniye ileri
- **Sola kaydır:** 10 saniye geri

---

## 🎛️ İleri Seviye: Context API Kullanımı

Kendi özel kontrollerinizi oluşturabilirsiniz:

```tsx
import {
  PlayerProvider,
  usePlayerContext,
  VideoPlayer
} from '@alper/video-player';
import '@alper/video-player/styles.css';

function CustomControls() {
  const {
    videoState,
    play,
    pause,
    seek,
    setVolume,
    toggleFullscreen,
    setPlaybackRate
  } = usePlayerContext();

  return (
    <div className="custom-controls">
      {/* Oynat/Duraklat */}
      <button onClick={() => videoState.playing ? pause() : play()}>
        {videoState.playing ? '⏸ Duraklat' : '▶ Oynat'}
      </button>

      {/* İleri/Geri */}
      <button onClick={() => seek(videoState.currentTime - 10)}>
        ⏪ -10s
      </button>
      <button onClick={() => seek(videoState.currentTime + 10)}>
        +10s ⏩
      </button>

      {/* Ses Kontrolü */}
      <input
        type="range"
        min="0"
        max="1"
        step="0.01"
        value={videoState.volume}
        onChange={(e) => setVolume(parseFloat(e.target.value))}
      />
      <span>{Math.round(videoState.volume * 100)}%</span>

      {/* Zaman Göstergesi */}
      <div>
        {formatTime(videoState.currentTime)} / {formatTime(videoState.duration)}
      </div>

      {/* Oynatma Hızı */}
      <select
        value={videoState.playbackRate}
        onChange={(e) => setPlaybackRate(parseFloat(e.target.value))}
      >
        <option value="0.5">0.5x</option>
        <option value="1">Normal</option>
        <option value="1.5">1.5x</option>
        <option value="2">2x</option>
      </select>

      {/* Tam Ekran */}
      <button onClick={toggleFullscreen}>
        {videoState.fullscreen ? '🗗 Çıkış' : '🗖 Tam Ekran'}
      </button>
    </div>
  );
}

function formatTime(seconds: number): string {
  const mins = Math.floor(seconds / 60);
  const secs = Math.floor(seconds % 60);
  return `${mins}:${secs.toString().padStart(2, '0')}`;
}

function App() {
  return (
    <PlayerProvider>
      <VideoPlayer
        src="/video.mp4"
        controls={false} // Yerleşik kontrolleri gizle
      />
      <CustomControls />
    </PlayerProvider>
  );
}
```

---

## 🔌 Next.js Entegrasyonu

Next.js'te SSR (Server-Side Rendering) sorunlarını önlemek için:

```tsx
'use client'; // App Router için

import dynamic from 'next/dynamic';
import '@alper/video-player/styles.css';

// VideoPlayer'ı client-side only olarak yükle
const VideoPlayer = dynamic(
  () => import('@alper/video-player').then(mod => mod.VideoPlayer),
  { ssr: false }
);

export default function VideoPage() {
  return (
    <div className="container">
      <h1>Video Player</h1>
      <VideoPlayer
        src="/videos/demo.mp4"
        poster="/images/poster.jpg"
      />
    </div>
  );
}
```

---

## 📊 Props API Referansı

### VideoPlayerProps

| Prop | Tip | Varsayılan | Açıklama |
|------|-----|-----------|----------|
| `src` | `string` | **zorunlu** | Video URL'i (MP4, HLS, vb.) |
| `poster` | `string` | - | Poster resim URL'i |
| `autoplay` | `boolean` | `false` | Otomatik oynat |
| `loop` | `boolean` | `false` | Döngü modu |
| `muted` | `boolean` | `false` | Sessiz başlat |
| `controls` | `boolean` | `true` | Kontrolleri göster |
| `subtitles` | `SubtitleTrack[]` | - | Altyazı listesi |
| `theme` | `PlayerTheme` | - | Renk teması |
| `keyboardShortcuts` | `boolean` | `true` | Klavye desteği |
| `pictureInPicture` | `boolean` | `true` | PiP desteği |
| `className` | `string` | - | CSS sınıfı |
| `style` | `CSSProperties` | - | Inline stil |

### Event Callbacks

| Callback | Parametre | Açıklama |
|----------|-----------|----------|
| `onPlay` | `() => void` | Video başladığında |
| `onPause` | `() => void` | Video durduğunda |
| `onEnded` | `() => void` | Video bittiğinde |
| `onTimeUpdate` | `(time: number) => void` | Zaman güncellendiğinde |
| `onVolumeChange` | `(volume: number) => void` | Ses değiştiğinde |
| `onError` | `(error: Error) => void` | Hata oluştuğunda |
| `onLoadedMetadata` | `() => void` | Metadata yüklendiğinde |
| `onSeeking` | `() => void` | Arama başladığında |
| `onSeeked` | `() => void` | Arama bittiğinde |

### SubtitleTrack

```typescript
interface SubtitleTrack {
  label: string;      // Görünen isim (ör: "Türkçe")
  src: string;        // Altyazı dosya URL'i
  srcLang: string;    // Dil kodu (ör: "tr", "en")
}
```

### PlayerTheme

```typescript
interface PlayerTheme {
  primaryColor?: string;      // Ana renk (varsayılan: #ef4444)
  accentColor?: string;       // Vurgu rengi (varsayılan: #dc2626)
  backgroundColor?: string;   // Arka plan rengi
  textColor?: string;         // Metin rengi
}
```

---

## 🎯 usePlayerContext Hook API

```typescript
const {
  // Video State
  videoState: {
    playing: boolean;
    currentTime: number;
    duration: number;
    buffered: TimeRanges;
    volume: number;
    muted: boolean;
    playbackRate: number;
    fullscreen: boolean;
    pictureInPicture: boolean;
    loading: boolean;
    error: string | null;
    seeking: boolean;
  },

  // UI State
  uiState: {
    controlsVisible: boolean;
    settingsOpen: boolean;
    volumeControlOpen: boolean;
  },

  // Settings
  settings: {
    quality: string | null;
    subtitle: string | null;
    playbackRate: number;
  },

  // Actions
  play: () => void;
  pause: () => void;
  seek: (time: number) => void;
  setVolume: (volume: number) => void;
  toggleMute: () => void;
  setPlaybackRate: (rate: number) => void;
  toggleFullscreen: () => void;
  togglePictureInPicture: () => void;

} = usePlayerContext();
```

---

## 💡 Kullanım Örnekleri

### 1. Analytics Entegrasyonu

```tsx
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function AnalyticsVideo() {
  const trackEvent = (event: string, data?: any) => {
    // Analytics servisinize gönderin
    console.log('Analytics:', event, data);
  };

  return (
    <VideoPlayer
      src="/video.mp4"
      onPlay={() => trackEvent('video_play')}
      onPause={() => trackEvent('video_pause')}
      onEnded={() => trackEvent('video_complete')}
      onTimeUpdate={(time) => {
        // Her %25'te bir event gönder
        if (time % 25 === 0) {
          trackEvent('video_progress', { percentage: time });
        }
      }}
      onError={(error) => trackEvent('video_error', { message: error.message })}
    />
  );
}
```

### 2. Playlist Sistemi

```tsx
import { useState } from 'react';
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

const playlist = [
  { id: 1, title: 'Video 1', src: '/videos/1.mp4' },
  { id: 2, title: 'Video 2', src: '/videos/2.mp4' },
  { id: 3, title: 'Video 3', src: '/videos/3.mp4' },
];

function PlaylistPlayer() {
  const [currentIndex, setCurrentIndex] = useState(0);
  const currentVideo = playlist[currentIndex];

  const handleEnded = () => {
    // Sonraki videoya geç
    if (currentIndex < playlist.length - 1) {
      setCurrentIndex(currentIndex + 1);
    }
  };

  return (
    <div>
      <VideoPlayer
        key={currentVideo.id}
        src={currentVideo.src}
        onEnded={handleEnded}
      />

      <div className="playlist">
        {playlist.map((video, index) => (
          <button
            key={video.id}
            onClick={() => setCurrentIndex(index)}
            className={index === currentIndex ? 'active' : ''}
          >
            {video.title}
          </button>
        ))}
      </div>
    </div>
  );
}
```

### 3. Çoklu Kalite Desteği

```tsx
import { VideoPlayer } from '@alper/video-player';
import '@alper/video-player/styles.css';

function QualityVideo() {
  // HLS kullanıyorsanız otomatik kalite seçimi vardır
  // Manuel kalite için farklı kaynak URL'leri kullanabilirsiniz

  return (
    <VideoPlayer
      src="/videos/stream/master.m3u8" // HLS master playlist
      // Otomatik olarak kaliteler algılanır ve ayarlarda gösterilir
    />
  );
}
```

---

## 🐛 Sorun Giderme

### CSS Stilleri Yüklenmiyor

Emin olun ki CSS dosyasını import ettiniz:

```tsx
import '@alper/video-player/styles.css';
```

### HLS Videoları Çalışmıyor

1. `hls.js` yüklü mü kontrol edin:
```bash
pnpm add hls.js
```

2. Video URL'inin `.m3u8` uzantılı olduğundan emin olun

### TypeScript Hataları

`tsconfig.json`'da `skipLibCheck: true` ayarlayın veya paketi güncelleyin:

```bash
pnpm update @alper/video-player
```

### Next.js'te Hydration Hatası

VideoPlayer'ı `dynamic` import ile yükleyin (`ssr: false`):

```tsx
const VideoPlayer = dynamic(
  () => import('@alper/video-player').then(mod => mod.VideoPlayer),
  { ssr: false }
);
```

---

## 📦 Bundle Boyutu

- **Gzipped:** ~8KB (hls.js hariç)
- **hls.js ile:** ~100KB (optional, sadece HLS kullanıyorsanız yüklenir)

---

## 🔄 Güncelleme

```bash
# En son versiyonu yükle
pnpm update @alper/video-player

# Belirli bir versiyonu yükle
pnpm add @alper/video-player@0.2.0

# Hangi versiyon yüklü?
pnpm list @alper/video-player
```

---

## 📄 Lisans

MIT

---

## 💬 Destek

Sorularınız için projeyi geliştiren kişiyle iletişime geçin.