shoptime/com.twin.app.shoptime/.docs/MediaPlayer-v2-README.md

# MediaPlayer.v2 - 최적화된 비디오 플레이어

**위치**: `src/components/VideoPlayer/MediaPlayer.v2.jsx`

---

## 📊 개요

webOS 환경에 최적화된 경량 비디오 플레이어 컴포넌트입니다.
기존 MediaPlayer.jsx의 핵심 기능은 유지하면서 불필요한 복잡도를 제거했습니다.

### 주요 개선사항

| 항목 | 기존 | v2 | 개선율 |
|------|------|-----|--------|
| **코드 라인** | 2,595 | 388 | **85%↓** |
| **상태 변수** | 20+ | 7 | **65%↓** |
| **Props** | 70+ | 18 | **74%↓** |
| **타이머/Job** | 8 | 1 | **87%↓** |
| **필수 기능** | 100% | 100% | **✅ 유지** |

---

## ✨ 주요 기능

### 1. Modal ↔ Fullscreen 전환
```javascript
// Modal 모드로 시작
<MediaPlayerV2
  src="video.mp4"
  panelInfo={{ modal: true, modalContainerId: 'product-123' }}
  onClick={() => dispatch(switchMediaToFullscreen())}
  style={modalStyle}  // MediaPanel에서 계산
/>

// 클릭 시 자동으로 Fullscreen으로 전환
```

### 2. 기본 재생 제어
```javascript
const playerRef = useRef();

// API 메서드
playerRef.current.play();
playerRef.current.pause();
playerRef.current.seek(30);
playerRef.current.getMediaState();
playerRef.current.showControls();
playerRef.current.hideControls();
```

### 3. isPaused 동기화
```javascript
// Modal 모드에서 다른 패널이 위로 올라오면 자동 일시정지
<MediaPlayerV2
  panelInfo={{
    modal: true,
    isPaused: true  // 자동으로 pause() 호출
  }}
/>
```

### 4. webOS / 브라우저 자동 감지
```javascript
// webOS: Media 컴포넌트
// 브라우저: TReactPlayer
// YouTube: TReactPlayer

// 자동으로 적절한 컴포넌트 선택
<MediaPlayerV2 src="video.mp4" />
<MediaPlayerV2 src="https://youtube.com/watch?v=xxx" />
```

---

## 📐 Props

### 필수 Props

```typescript
interface MediaPlayerV2Props {
  // 비디오 소스 (필수)
  src: string;
}
```

### 선택 Props

```typescript
interface MediaPlayerV2Props {
  // 비디오 설정
  type?: string;              // 기본: 'video/mp4'
  thumbnailUrl?: string;

  // 재생 제어
  autoPlay?: boolean;         // 기본: false
  loop?: boolean;             // 기본: false
  muted?: boolean;            // 기본: false

  // Modal 전환
  disabled?: boolean;         // Modal에서 true
  spotlightDisabled?: boolean;
  onClick?: () => void;       // Modal 클릭 시
  style?: CSSProperties;      // Modal fixed position
  modalClassName?: string;
  modalScale?: number;

  // 패널 정보
  panelInfo?: {
    modal?: boolean;
    modalContainerId?: string;
    isPaused?: boolean;
  };

  // 콜백
  onEnded?: (e: Event) => void;
  onError?: (e: Event) => void;
  onBackButton?: (e: Event) => void;
  onLoadStart?: (e: Event) => void;
  onTimeUpdate?: (e: Event) => void;
  onLoadedData?: (e: Event) => void;
  onLoadedMetadata?: (e: Event) => void;
  onDurationChange?: (e: Event) => void;

  // Spotlight
  spotlightId?: string;       // 기본: 'mediaPlayerV2'

  // 비디오 컴포넌트
  videoComponent?: React.ComponentType;

  // ReactPlayer 설정
  reactPlayerConfig?: object;

  // 기타
  children?: React.ReactNode;  // <source>, <track> tags
  className?: string;
}
```

---

## 💻 사용 예제

### 기본 사용

```javascript
import MediaPlayerV2 from '../components/VideoPlayer/MediaPlayer.v2';

function MyComponent() {
  return (
    <MediaPlayerV2
      src="https://example.com/video.mp4"
      autoPlay
      onEnded={() => console.log('Video ended')}
    />
  );
}
```

### Modal 모드 (MediaPanel에서 사용)

```javascript
import MediaPlayerV2 from '../components/VideoPlayer/MediaPlayer.v2';

function MediaPanel({ panelInfo }) {
  const [modalStyle, setModalStyle] = useState({});

  useEffect(() => {
    if (panelInfo.modal && panelInfo.modalContainerId) {
      const node = document.querySelector(
        `[data-spotlight-id="${panelInfo.modalContainerId}"]`
      );
      const rect = node.getBoundingClientRect();

      setModalStyle({
        position: 'fixed',
        top: rect.top + 'px',
        left: rect.left + 'px',
        width: rect.width + 'px',
        height: rect.height + 'px',
      });
    }
  }, [panelInfo]);

  const handleVideoClick = () => {
    if (panelInfo.modal) {
      dispatch(switchMediaToFullscreen());
    }
  };

  return (
    <MediaPlayerV2
      src={panelInfo.showUrl}
      thumbnailUrl={panelInfo.thumbnailUrl}
      disabled={panelInfo.modal}
      spotlightDisabled={panelInfo.modal}
      onClick={handleVideoClick}
      style={panelInfo.modal ? modalStyle : {}}
      panelInfo={panelInfo}
    />
  );
}
```

### API 사용

```javascript
import { useRef } from 'react';
import MediaPlayerV2 from '../components/VideoPlayer/MediaPlayer.v2';

function MyComponent() {
  const playerRef = useRef();

  const handlePlay = () => {
    playerRef.current?.play();
  };

  const handlePause = () => {
    playerRef.current?.pause();
  };

  const handleSeek = (time) => {
    playerRef.current?.seek(time);
  };

  const getState = () => {
    const state = playerRef.current?.getMediaState();
    console.log(state);
    // {
    //   currentTime: 10.5,
    //   duration: 120,
    //   paused: false,
    //   loading: false,
    //   error: null,
    //   playbackRate: 1,
    //   proportionPlayed: 0.0875
    // }
  };

  return (
    <>
      <MediaPlayerV2
        ref={playerRef}
        src="video.mp4"
      />

      <button onClick={handlePlay}>Play</button>
      <button onClick={handlePause}>Pause</button>
      <button onClick={() => handleSeek(30)}>Seek 30s</button>
      <button onClick={getState}>Get State</button>
    </>
  );
}
```

### webOS <source> 태그 사용

```javascript
<MediaPlayerV2 src="video.mp4">
  <source src="video.mp4" type="video/mp4" />
  <track kind="subtitles" src="subtitles.vtt" default />
</MediaPlayerV2>
```

### YouTube 재생

```javascript
<MediaPlayerV2
  src="https://www.youtube.com/watch?v=dQw4w9WgXcQ"
  reactPlayerConfig={{
    youtube: {
      playerVars: {
        controls: 0,
        autoplay: 1,
      }
    }
  }}
/>
```

---

## 🔧 API 메서드

ref를 통해 다음 메서드에 접근할 수 있습니다:

```typescript
interface MediaPlayerV2API {
  // 재생 제어
  play(): void;
  pause(): void;
  seek(timeIndex: number): void;

  // 상태 조회
  getMediaState(): {
    currentTime: number;
    duration: number;
    paused: boolean;
    loading: boolean;
    error: Error | null;
    playbackRate: number;
    proportionPlayed: number;
  };

  // Controls 제어
  showControls(): void;
  hideControls(): void;
  toggleControls(): void;
  areControlsVisible(): boolean;

  // Video Node 접근
  getVideoNode(): HTMLVideoElement | ReactPlayerInstance;
}
```

---

## 🎯 제거된 기능

다음 기능들은 MediaPanel 사용 케이스에 불필요하여 제거되었습니다:

```
❌ MediaSlider (seek bar)
❌ jumpBy, fastForward, rewind
❌ playbackRate 조정
❌ QR코드 오버레이
❌ 전화번호 오버레이
❌ 테마 인디케이터
❌ 복잡한 피드백 시스템 (8개 Job → 1개 setTimeout)
❌ FloatingLayer
❌ Redux 통합
❌ TabContainer 동기화
❌ Announce/Accessibility 복잡계
❌ MediaTitle, infoComponents
```

필요하다면 기존 MediaPlayer.jsx를 사용하세요.

---

## 🚀 성능

### 메모리 사용량

- **타이머**: 8개 Job → 1개 setTimeout
- **이벤트 리스너**: 최소화 (video element events만)
- **상태 변수**: 7개 (20+개에서 감소)

### 렌더링 성능

- **useMemo**: 계산 비용이 큰 값 캐싱
- **useCallback**: 함수 재생성 방지
- **조건부 렌더링**: 불필요한 DOM 요소 제거

---

## 🔄 마이그레이션 가이드

### 기존 MediaPlayer.jsx에서 마이그레이션

대부분의 props는 호환됩니다:

```javascript
// 기존
import { VideoPlayer } from '../components/VideoPlayer/MediaPlayer';

// 새로운
import MediaPlayerV2 from '../components/VideoPlayer/MediaPlayer.v2';
```

제거된 props:
- `jumpBy`, `initialJumpDelay`, `jumpDelay`
- `playbackRateHash`
- `onFastForward`, `onRewind`, `onJumpBackward`, `onJumpForward`
- `feedbackHideDelay`, `miniFeedbackHideDelay`
- `noMediaSliderFeedback`, `noMiniFeedback`, `noSlider`
- `title`, `infoComponents`
- 기타 PlayerPanel 전용 props

---

## 📝 Notes

### Modal 전환 작동 방식

1. **MediaPanel**이 `getBoundingClientRect()`로 스타일 계산
2. **MediaPlayerV2**는 받은 `style`을 그대로 적용
3. `modal` 플래그에 따라 controls/spotlight 활성화 제어

→ **MediaPlayerV2는 전환 로직 구현 불필요**

### webOS 호환성

- `window.PalmSystem` 존재 시 `Media` 컴포넌트 사용
- 브라우저에서는 `TReactPlayer` 사용
- YouTube URL은 항상 `TReactPlayer` 사용

---

## 🐛 알려진 제약사항

1. **Seek bar 없음**: 단순 재생만 지원
2. **빠르기 조정 없음**: 배속 재생 미지원
3. **간단한 Controls**: 재생/일시정지 버튼만

복잡한 컨트롤이 필요하다면 기존 `MediaPlayer.jsx` 사용을 권장합니다.

---

## 📚 관련 문서

- [비디오 플레이어 분석 문서](.docs/video-player-analysis-and-optimization-plan.md)
- [Modal 전환 상세 분석](.docs/modal-transition-analysis.md)