diff --git a/DOCUMENTATION.md b/DOCUMENTATION.md new file mode 100644 index 0000000..50e2418 --- /dev/null +++ b/DOCUMENTATION.md @@ -0,0 +1,1347 @@ +# 📚 Video Player - Kapsamlı Dokümantasyon + +Modern, hafif ve özellik açısından zengin bir React video player kütüphanesi. Bu dokümantasyon, kütüphaneyi projelerinizde kullanmak için ihtiyacınız olan her şeyi içerir. + +## 📦 Kurulum + +### NPM ile Kurulum + +```bash +npm install @alper/video-player +``` + +### Yarn ile Kurulum + +```bash +yarn add @alper/video-player +``` + +### Peer Dependencies + +Video player, React 18+ gerektirmektedir: + +```bash +npm install react react-dom +``` + +### Opsiyonel Bağımlılıklar + +HLS streaming desteği için hls.js otomatik olarak yüklenecektir (gerektiğinde): + +```bash +npm install hls.js # Opsiyonel +``` + +--- + +## 🚀 Hızlı Başlangıç + +### Basit Kullanım + +```tsx +import { VideoPlayer } from '@alper/video-player' +import '@alper/video-player/styles.css' + +function App() { + return ( + + ) +} +``` + +### TypeScript Desteği + +Kütüphane tam TypeScript desteğine sahiptir ve tip tanımları otomatik olarak gelir: + +```tsx +import { VideoPlayer, VideoPlayerProps } from '@alper/video-player' +import '@alper/video-player/styles.css' + +const MyPlayer: React.FC = () => { + const props: VideoPlayerProps = { + src: "video.mp4", + autoplay: false, + loop: true, + } + + return +} +``` + +--- + +## 🎬 Özellikler + +### ✅ Temel Özellikler + +- ▶️ **Oynatma Kontrolleri**: Play, pause, seek +- 🔊 **Ses Kontrolü**: Volume slider ve mute +- ⚡ **Hız Kontrolü**: 0.25x - 2x oynatma hızı +- 🔄 **Loop Desteği**: Sürekli tekrar +- 🖼️ **Poster Resmi**: Video başlamadan önce görünen thumbnail +- ⌨️ **Klavye Kısayolları**: 15+ klavye kısayolu +- 📱 **Touch Gesture'lar**: Mobil cihazlar için özel kontroller + +### 🎨 Gelişmiş Özellikler + +- 📺 **HLS Streaming**: .m3u8 dosyaları için otomatik HLS desteği +- 📝 **Altyazı Desteği**: WebVTT ve SRT formatları +- 🎵 **Çoklu Ses Kanalı**: Farklı dil seçenekleri +- 🎯 **Kalite Seçimi**: HLS stream'lerinde otomatik kalite geçişi +- 🖥️ **Fullscreen**: Native fullscreen API desteği +- 📺 **Picture-in-Picture**: PIP mode desteği +- 🌍 **i18n Desteği**: İngilizce ve Türkçe dil desteği +- 🎨 **Tema Özelleştirme**: CSS değişkenleri ile kolay özelleştirme + +### ⚡ Performans + +- 📦 **Küçük Boyut**: Sadece ~15KB (gzipped) +- 🚀 **Sıfır Runtime Bağımlılık**: React dışında bağımlılık yok +- 🔄 **Lazy Loading**: HLS.js sadece gerektiğinde yüklenir +- 🎯 **Optimize Edilmiş**: Tree-shakeable exports + +--- + +## 📖 API Referansı + +### VideoPlayer Props + +| Prop | Tip | Varsayılan | Açıklama | +|------|-----|------------|----------| +| `src` | `string` | **zorunlu** | Video kaynağı URL (MP4, WebM, HLS) | +| `poster` | `string` | - | Poster/thumbnail resmi URL'si | +| `autoplay` | `boolean` | `false` | Otomatik oynatma | +| `loop` | `boolean` | `false` | Video tekrarı | +| `muted` | `boolean` | `false` | Sessiz başlat | +| `controls` | `boolean` | `true` | Kontrolleri göster | +| `subtitles` | `SubtitleTrack[]` | `[]` | Altyazı track'leri | +| `theme` | `PlayerTheme` | - | Özel tema renkleri | +| `language` | `string` | `'tr'` | Arayüz dili (`'tr'` veya `'en'`) | +| `keyboardShortcuts` | `boolean` | `true` | Klavye kısayollarını etkinleştir | +| `pictureInPicture` | `boolean` | `true` | PIP butonunu göster | +| `className` | `string` | - | Özel CSS class'ı | +| `style` | `CSSProperties` | - | Inline style'lar | +| `onPlay` | `() => void` | - | Oynatma başladığında | +| `onPause` | `() => void` | - | Oynatma durduğunda | +| `onEnded` | `() => void` | - | Video bittiğinde | +| `onTimeUpdate` | `(time: number) => void` | - | Zaman güncellendiğinde | +| `onVolumeChange` | `(volume: number) => void` | - | Ses seviyesi değiştiğinde | +| `onError` | `(error: Error) => void` | - | Hata oluştuğunda | +| `onLoadedMetadata` | `() => void` | - | Metadata yüklendiğinde | +| `onSeeking` | `() => void` | - | Seek başladığında | +| `onSeeked` | `() => void` | - | Seek bittiğinde | + +### SubtitleTrack + +```typescript +interface SubtitleTrack { + src: string // Altyazı dosyası URL'si (.vtt veya .srt) + lang: string // Dil kodu (örn: 'en', 'tr') + label: string // Görüntülenecek etiket + default?: boolean // Varsayılan altyazı olarak ayarla +} +``` + +### AudioTrack + +```typescript +interface AudioTrack { + name: string // Ses track'inin adı + language: string // Dil kodu + url: string // Ses dosyası URL'si + groupId: string // Grup ID'si + default?: boolean // Varsayılan olarak seç +} +``` + +### VideoQuality + +```typescript +interface VideoQuality { + height?: number // Video yüksekliği (px) + label: string // Görüntülenecek etiket (örn: "1080p") + width?: number // Video genişliği (px) + bitrate?: number // Bitrate (bps) + levelIndex?: number // HLS level index +} +``` + +### PlayerTheme + +```typescript +interface PlayerTheme { + primaryColor?: string // Ana renk (varsayılan: #ef4444) + accentColor?: string // Vurgu rengi (varsayılan: #dc2626) + backgroundColor?: string // Arkaplan rengi (varsayılan: #000000) + textColor?: string // Yazı rengi (varsayılan: #ffffff) +} +``` + +--- + +## 💡 Kullanım Örnekleri + +### 1. Basit Video Oynatma + +En temel kullanım: + +```tsx +import { VideoPlayer } from '@alper/video-player' +import '@alper/video-player/styles.css' + +function SimplePlayer() { + return ( + + ) +} +``` + +### 2. Otomatik Oynatma ve Loop + +Video otomatik başlasın ve sürekli tekrarlansın: + +```tsx + +``` + +### 3. Altyazılı Video + +Çoklu altyazı desteği ile: + +```tsx + +``` + +### 4. HLS Streaming + +HLS video için (hls.js otomatik yüklenir): + +```tsx + +``` + +HLS streaming ile kalite seçimi otomatik olarak aktif olur. + +### 5. Event Handler'lar ile İleri Seviye Kullanım + +Video olaylarını dinleme: + +```tsx +import { useState } from 'react' +import { VideoPlayer } from '@alper/video-player' + +function AdvancedPlayer() { + const [currentTime, setCurrentTime] = useState(0) + const [isPlaying, setIsPlaying] = useState(false) + + return ( +
+ { + console.log('Video başladı!') + setIsPlaying(true) + }} + onPause={() => { + console.log('Video durdu!') + setIsPlaying(false) + }} + onTimeUpdate={(time) => { + setCurrentTime(time) + }} + onEnded={() => { + console.log('Video bitti!') + // Örnek: Sonraki videoya geç + }} + onError={(error) => { + console.error('Video hatası:', error) + // Hata gösterimi veya fallback + }} + /> + +
+

Durum: {isPlaying ? 'Oynatılıyor' : 'Durdu'}

+

Zaman: {Math.floor(currentTime)}s

+
+
+ ) +} +``` + +### 6. Özel Tema + +Kendi renk şemanızla özelleştirme: + +```tsx + +``` + +### 7. Türkçe Arayüz + +Türkçe dil desteği: + +```tsx + +``` + +### 8. Klavye Kısayolları Devre Dışı + +Bazı durumlarda klavye kısayollarını kapatmak isteyebilirsiniz: + +```tsx + +``` + +### 9. Responsive Layout + +Farklı ekran boyutlarında: + +```tsx +
+ +
+``` + +### 10. Video Playlist + +Sıralı video oynatma: + +```tsx +import { useState } from 'react' +import { VideoPlayer } from '@alper/video-player' + +const videos = [ + { id: 1, src: '/videos/episode1.mp4', title: 'Bölüm 1' }, + { id: 2, src: '/videos/episode2.mp4', title: 'Bölüm 2' }, + { id: 3, src: '/videos/episode3.mp4', title: 'Bölüm 3' }, +] + +function Playlist() { + const [currentIndex, setCurrentIndex] = useState(0) + + const handleEnded = () => { + // Sonraki videoya geç + if (currentIndex < videos.length - 1) { + setCurrentIndex(currentIndex + 1) + } + } + + return ( +
+

{videos[currentIndex].title}

+ + +
+ {videos.map((video, index) => ( + + ))} +
+
+ ) +} +``` + +--- + +## ⌨️ Klavye Kısayolları + +Video player, kullanıcı deneyimini geliştirmek için kapsamlı klavye desteği sunar: + +| Tuş | Aksiyon | +|-----|---------| +| `Space` veya `K` | Oynat/Duraklat | +| `←` (Sol Ok) | 5 saniye geri sar | +| `→` (Sağ Ok) | 5 saniye ileri sar | +| `J` | 10 saniye geri sar | +| `L` | 10 saniye ileri sar | +| `↑` (Yukarı Ok) | Ses seviyesini artır (%5) | +| `↓` (Aşağı Ok) | Ses seviyesini azalt (%5) | +| `M` | Sessiz/Sesli | +| `F` | Tam ekran aç/kapat | +| `P` | Picture-in-Picture | +| `0` | Başa dön (%0) | +| `1-9` | İlgili yüzdeye atla (%10-%90) | +| `Home` | Başa dön | +| `End` | Sona git | +| `<` | Oynatma hızını azalt (0.25x) | +| `>` | Oynatma hızını artır (0.25x) | + +**Not:** Klavye kısayolları sadece video player'a focus edildiğinde çalışır. + +--- + +## 📱 Touch Gesture'lar + +Mobil cihazlarda kullanıcı deneyimini geliştiren touch gesture'lar: + +### Temel Gesture'lar + +- **Tek Dokunuş**: Oynat/Duraklat +- **Çift Dokunuş (Sol)**: 10 saniye geri sar +- **Çift Dokunuş (Sağ)**: 10 saniye ileri sar + +### Swipe Gesture'ları + +- **Sağa Kaydır**: İleri sar (kaydırma mesafesine göre) +- **Sola Kaydır**: Geri sar (kaydırma mesafesine göre) +- **Yukarı Kaydır**: Ses seviyesini artır +- **Aşağı Kaydır**: Ses seviyesini azalt + +### Pinch & Zoom + +- **Pinch**: Video zoom (bazı tarayıcılarda) + +--- + +## 🎨 Stil ve Özelleştirme + +### CSS Değişkenleri + +Video player, CSS değişkenleri kullanarak kolayca özelleştirilebilir. İşte tüm değişkenler: + +```css +:root { + /* Ana Renkler */ + --player-primary: #ef4444; /* Ana renk */ + --player-primary-hover: #dc2626; /* Hover rengi */ + --player-primary-active: #b91c1c; /* Active rengi */ + --player-primary-light: rgba(239, 68, 68, 0.2); /* Açık renk */ + + /* Arkaplan Renkleri */ + --player-bg: #000000; /* Ana arkaplan */ + --player-bg-controls: rgba(0, 0, 0, 0.85); /* Kontrol paneli */ + --player-bg-overlay: rgba(0, 0, 0, 0.6); /* Overlay */ + --player-bg-menu: rgba(20, 20, 20, 0.95); /* Menu arkaplan */ + + /* Yazı Renkleri */ + --player-text: #ffffff; /* Ana yazı */ + --player-text-secondary: #d1d5db; /* İkincil yazı */ + --player-text-muted: #9ca3af; /* Soluk yazı */ + + /* Kenarlık & Ayırıcı */ + --player-border: #374151; + --player-divider: rgba(255, 255, 255, 0.1); + + /* Progress & Buffered */ + --player-buffered: rgba(239, 68, 68, 0.3); + --player-progress-bg: rgba(255, 255, 255, 0.3); + + /* Gölgeler */ + --player-shadow-sm: 0 1px 2px 0 rgba(0, 0, 0, 0.05); + --player-shadow-md: 0 4px 6px -1px rgba(0, 0, 0, 0.1); + --player-shadow-lg: 0 10px 15px -3px rgba(0, 0, 0, 0.1); + + /* Geçişler */ + --player-transition-fast: 150ms; + --player-transition-normal: 250ms; + --player-transition-slow: 400ms; + + /* Z-index */ + --player-z-video: 1; + --player-z-subtitle: 10; + --player-z-controls: 20; + --player-z-menu: 30; + --player-z-loading: 40; + + /* Boşluklar */ + --player-spacing-xs: 6px; + --player-spacing-sm: 10px; + --player-spacing-md: 14px; + --player-spacing-lg: 20px; + --player-spacing-xl: 28px; + + /* Border Radius */ + --player-radius-sm: 4px; + --player-radius-md: 6px; + --player-radius-lg: 8px; + --player-radius-full: 9999px; + + /* İkon Boyutları */ + --player-icon-sm: 20px; + --player-icon-md: 28px; + --player-icon-lg: 36px; + --player-icon-xl: 56px; +} +``` + +### Tema Özelleştirme Örnekleri + +#### Koyu Mavi Tema + +```css +:root { + --player-primary: #3b82f6; + --player-primary-hover: #2563eb; + --player-primary-active: #1d4ed8; + --player-bg: #0f172a; +} +``` + +```tsx +// veya JavaScript ile + +``` + +#### Yeşil Tema + +```css +:root { + --player-primary: #10b981; + --player-primary-hover: #059669; + --player-primary-active: #047857; +} +``` + +#### Mor Tema + +```css +:root { + --player-primary: #8b5cf6; + --player-primary-hover: #7c3aed; + --player-primary-active: #6d28d9; +} +``` + +### Özel CSS ile Özelleştirme + +Daha fazla kontrol için özel CSS yazabilirsiniz: + +```css +/* Video player container boyutu */ +.video-player { + max-width: 1200px; + margin: 0 auto; + border-radius: 12px; + overflow: hidden; + box-shadow: 0 20px 50px rgba(0, 0, 0, 0.3); +} + +/* Kontrol paneli opacity */ +.video-controls { + background: rgba(0, 0, 0, 0.95) !important; +} + +/* Progress bar yüksekliği */ +.progress-bar { + height: 6px !important; +} + +/* Button boyutları */ +.control-button { + width: 48px !important; + height: 48px !important; +} +``` + +--- + +## 🔧 Gelişmiş Kullanım + +### Context API ile Video Kontrolü + +Video player'ın context'ini kullanarak programatik kontrol: + +```tsx +import { VideoPlayer, usePlayerContext, PlayerProvider } from '@alper/video-player' + +function VideoControls() { + const { + play, + pause, + seek, + setVolume, + toggleFullscreen, + videoState + } = usePlayerContext() + + return ( +
+ + + + + + +

Oynatılıyor: {videoState.playing ? 'Evet' : 'Hayır'}

+

Süre: {videoState.duration}s

+

Mevcut: {videoState.currentTime}s

+
+ ) +} + +function App() { + return ( + + + + + ) +} +``` + +### Custom Hook'lar Kullanımı + +Kendi player'ınızı oluşturmak için hook'ları kullanabilirsiniz: + +```tsx +import { useKeyboardShortcuts, useTouchGestures } from '@alper/video-player' + +function CustomPlayer() { + const videoRef = useRef(null) + + // Klavye kısayollarını ekle + useKeyboardShortcuts(videoRef, { + onPlayPause: () => { + if (videoRef.current?.paused) { + videoRef.current?.play() + } else { + videoRef.current?.pause() + } + }, + onSeek: (seconds) => { + if (videoRef.current) { + videoRef.current.currentTime += seconds + } + } + }) + + // Touch gesture'ları ekle + useTouchGestures(videoRef, { + onDoubleTapLeft: () => console.log('Geri sar'), + onDoubleTapRight: () => console.log('İleri sar'), + }) + + return