Add npm registry configuration for Gitea
This commit is contained in:
hibna
+601
@@ -0,0 +1,601 @@
|
||||
# @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.
|
||||
|
||||
## 📦 Kurulum
|
||||
|
||||
### Gitea Self-Hosted Registry'den Yükleme
|
||||
|
||||
1. **Projenizde `.npmrc` dosyası oluşturun:**
|
||||
|
||||
```ini
|
||||
@alper:registry=https://gitea.yourdomain.com/api/packages/your-username/npm/
|
||||
//gitea.yourdomain.com/api/packages/your-username/npm/:_authToken=${GITEA_TOKEN}
|
||||
```
|
||||
|
||||
2. **Environment variable ayarlayın (önerilen):**
|
||||
|
||||
```bash
|
||||
# Linux/Mac
|
||||
export GITEA_TOKEN=your-gitea-access-token
|
||||
|
||||
# Windows (PowerShell)
|
||||
$env:GITEA_TOKEN="your-gitea-access-token"
|
||||
|
||||
# veya .env dosyasına ekleyin
|
||||
GITEA_TOKEN=your-gitea-access-token
|
||||
```
|
||||
|
||||
3. **Paketi yükleyin:**
|
||||
|
||||
```bash
|
||||
pnpm add @alper/video-player
|
||||
# veya
|
||||
npm install @alper/video-player
|
||||
# veya
|
||||
yarn add @alper/video-player
|
||||
```
|
||||
|
||||
---
|
||||
|
||||
## 🚀 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.
|
||||
Reference in New Issue
Block a user