hibna
568 lines
12 KiB
Markdown
568 lines
12 KiB
Markdown
# @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.
|