player/README-USAGE.md

@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:

@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):

# 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:

pnpm add @alper/video-player
# veya
npm install @alper/video-player
# veya
yarn add @alper/video-player

---

🚀 Temel Kullanım

Minimum Örnek

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

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

Özelliklerle Birlikte

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

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

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

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:

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:

'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

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

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

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

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

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

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:

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

HLS Videoları Çalışmıyor

1. hls.js yüklü mü kontrol edin:

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:

pnpm update @alper/video-player

Next.js'te Hydration Hatası

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

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

# 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.