Flutter 튜토리얼 21편: 비디오 재생

요약#

핵심 요지#

문제 정의: 앱에서 비디오를 재생하려면 플랫폼별 네이티브 플레이어를 다뤄야 하고, 컨트롤 UI도 직접 만들어야 한다.
핵심 주장: video_player¹ 패키지와 chewie²를 함께 사용하면 플랫폼 차이 없이 완성된 비디오 플레이어를 구현할 수 있다.
주요 근거: VideoPlayerController³로 비디오를 로드하고, AspectRatio와 VideoPlayer 위젯으로 화면에 표시하며, Chewie가 컨트롤 UI를 제공한다.
실무 기준: iOS 시뮬레이터에서는 에셋 비디오만 재생 가능하고, 네트워크 비디오는 실제 기기에서 테스트해야 한다.
한계: Linux와 Windows는 video_player를 지원하지 않는다.

문서가 설명하는 범위#

VideoPlayerController 초기화와 생명주기 관리
네트워크와 에셋 비디오 재생
재생 컨트롤 구현 (재생/일시정지, 탐색)
Chewie로 완성된 UI 구현

읽는 시간: 12분 | 난이도: 중급

참고 자료#

Play and pause a video - Flutter 공식 비디오 재생 가이드
video_player - 비디오 재생 플러그인
chewie - 비디오 플레이어 UI 패키지

문제 상황#

앱에서 비디오를 재생하는 것은 단순해 보이지만 여러 복잡한 문제가 있습니다.

비디오 재생의 어려움#

1
문제 1: 플랫폼별로 다른 네이티브 플레이어 (AVPlayer, ExoPlayer)
2
문제 2: 비디오 초기화는 비동기로 완료까지 시간 필요
3
문제 3: 메모리 관리 - 컨트롤러를 제대로 dispose하지 않으면 메모리 누수
4
문제 4: 재생 컨트롤 UI를 직접 만들어야 함

해결 방법#

Flutter의 video_player 패키지는 iOS에서 AVPlayer를, Android에서 ExoPlayer를 사용해서 비디오를 재생합니다. 통일된 API로 플랫폼 차이를 추상화합니다.

챕터 1: video_player 설정하기#

Why#

NOTE
비디오 재생 기능을 사용하려면 먼저 패키지를 설치하고 플랫폼별 권한을 설정해야 합니다.
네트워크 비디오를 재생하려면 인터넷 접근 권한이 필요합니다.
1
패키지 설치 → 권한 설정 → 컨트롤러 생성 → 비디오 재생

What#

NOTE
video_player 패키지는 iOS, Android, macOS, Web에서 비디오 재생을 지원합니다.
Linux와 Windows는 현재 지원하지 않습니다.

How#

TIP

패키지 설치

1
flutter pub add video_player

Android 권한 설정 (android/app/src/main/AndroidManifest.xml)

1
<manifest xmlns:android="http://schemas.android.com/apk/res/android">
2
    <application ...>
3
        ...
4
    </application>
5

6
    <!-- 네트워크 비디오 재생을 위해 필요 -->
7
    <uses-permission android:name="android.permission.INTERNET"/>
8
</manifest>

iOS 설정 (ios/Runner/Info.plist)

1
<key>NSAppTransportSecurity</key>
2
<dict>
3
  <key>NSAllowsArbitraryLoads</key>
4
  <true/>
5
</dict>

macOS 설정 (macos/Runner/DebugProfile.entitlements)

1
<key>com.apple.security.network.client</key>
2
<true/>

Watch out#

WARNING
iOS 시뮬레이터에서는 네트워크 비디오를 재생할 수 없습니다.
에셋 비디오만 테스트 가능하며, 네트워크 비디오는 실제 기기에서 테스트해야 합니다.
1
// 시뮬레이터에서 테스트할 때는 에셋 비디오 사용
2
VideoPlayerController.asset('assets/videos/sample.mp4')
3

4
// 실제 기기에서 네트워크 비디오 테스트
5
VideoPlayerController.networkUrl(Uri.parse('https://...'))

결론: video_player 패키지를 설치하고 플랫폼별 권한을 설정해야 비디오를 재생할 수 있습니다.

챕터 2: VideoPlayerController 초기화#

Why#

NOTE
비디오를 재생하려면 먼저 VideoPlayerController를 생성하고 초기화해야 합니다.
초기화는 비동기 작업이므로 완료될 때까지 기다려야 합니다.
graph LR A[Controller 생성] --> B[initialize 호출] B --> C[Future 완료 대기] C --> D[비디오 재생 가능]

What#

NOTE
VideoPlayerController는 비디오 소스(네트워크, 에셋, 파일)를 로드하고 재생을 제어합니다.
initialize()를 호출해서 비디오 메타데이터를 로드하고 재생 준비를 완료합니다.

How#

TIP

네트워크 비디오 초기화

1
import 'package:flutter/material.dart';
2
import 'package:video_player/video_player.dart';
3

4
class VideoScreen extends StatefulWidget {
5
  const VideoScreen({super.key});
6

7
  @override
8
  State<VideoScreen> createState() => _VideoScreenState();
9
}
10

11
class _VideoScreenState extends State<VideoScreen> {
12
  late VideoPlayerController _controller;
13
  late Future<void> _initializeVideoPlayerFuture;
14

15
  @override
16
  void initState() {
17
    super.initState();
18

19
    // 네트워크 비디오 컨트롤러 생성
20
    _controller = VideoPlayerController.networkUrl(
21
      Uri.parse(
22
        'https://flutter.github.io/assets-for-api-docs/assets/videos/butterfly.mp4',
23
      ),
24
    );
25

26
    // 초기화 Future 저장
27
    _initializeVideoPlayerFuture = _controller.initialize();
28
  }
29

30
  @override
31
  void dispose() {
32
    // 반드시 dispose 호출
33
    _controller.dispose();
34
    super.dispose();
35
  }
36

37
  @override
38
  Widget build(BuildContext context) {
39
    return const Placeholder(); // 다음 챕터에서 구현
40
  }
41
}

에셋 비디오 초기화

1
// pubspec.yaml에 에셋 등록 필요
2
// flutter:
3
//   assets:
4
//     - assets/videos/
5

6
_controller = VideoPlayerController.asset('assets/videos/sample.mp4');
7
_initializeVideoPlayerFuture = _controller.initialize();

파일 비디오 초기화 (웹 제외)

1
import 'dart:io';
2

3
_controller = VideoPlayerController.file(File('/path/to/video.mp4'));
4
_initializeVideoPlayerFuture = _controller.initialize();

Watch out#

WARNING
dispose()를 호출하지 않으면 메모리 누수가 발생합니다.
특히 리스트에서 여러 비디오를 다룰 때 주의해야 합니다.
1
@override
2
void dispose() {
3
  // 반드시 컨트롤러 해제
4
  _controller.dispose();
5
  super.dispose();
6
}
초기화 전에 play()를 호출하면 아무 일도 일어나지 않습니다. 반드시 initialize() 완료 후에 재생을 시작해야 합니다.

결론: VideoPlayerController를 생성하고 initialize()가 완료된 후에 비디오를 재생할 수 있습니다.

챕터 3: 비디오 화면에 표시하기#

Why#

NOTE
초기화된 비디오를 화면에 표시하려면 VideoPlayer 위젯을 사용합니다.
비디오 비율을 유지하려면 AspectRatio 위젯으로 감싸야 합니다.
1
초기화 완료 확인 → AspectRatio로 비율 유지 → VideoPlayer로 표시

What#

NOTE
VideoPlayer 위젯은 VideoPlayerController의 비디오를 화면에 렌더링합니다.
FutureBuilder를 사용해서 초기화 완료 상태를 처리합니다.

How#

TIP

기본 비디오 표시

1
@override
2
Widget build(BuildContext context) {
3
  return Scaffold(
4
    appBar: AppBar(title: const Text('비디오 플레이어')),
5
    body: FutureBuilder(
6
      future: _initializeVideoPlayerFuture,
7
      builder: (context, snapshot) {
8
        if (snapshot.connectionState == ConnectionState.done) {
9
          // 초기화 완료 - 비디오 표시
10
          return AspectRatio(
11
            aspectRatio: _controller.value.aspectRatio,
12
            child: VideoPlayer(_controller),
13
          );
14
        } else {
15
          // 초기화 중 - 로딩 표시
16
          return const Center(
17
            child: CircularProgressIndicator(),
18
          );
19
        }
20
      },
21
    ),
22
  );
23
}

에러 처리 추가

1
FutureBuilder(
2
  future: _initializeVideoPlayerFuture,
3
  builder: (context, snapshot) {
4
    if (snapshot.hasError) {
5
      return Center(
6
        child: Column(
7
          mainAxisAlignment: MainAxisAlignment.center,
8
          children: [
9
            const Icon(Icons.error, size: 48, color: Colors.red),
10
            const SizedBox(height: 16),
11
            Text('비디오 로드 실패: ${snapshot.error}'),
12
          ],
13
        ),
14
      );
15
    }
16

17
    if (snapshot.connectionState == ConnectionState.done) {
18
      return AspectRatio(
19
        aspectRatio: _controller.value.aspectRatio,
20
        child: VideoPlayer(_controller),
21
      );
22
    }
23

24
    return const Center(child: CircularProgressIndicator());
25
  },
26
)

전체 화면 비디오

1
SizedBox.expand(
2
  child: FittedBox(
3
    fit: BoxFit.cover,
4
    child: SizedBox(
5
      width: _controller.value.size.width,
6
      height: _controller.value.size.height,
7
      child: VideoPlayer(_controller),
8
    ),
9
  ),
10
)

Watch out#

WARNING
AspectRatio를 사용하지 않으면 비디오가 찌그러지거나 부모 크기에 맞춰 늘어납니다.
1
// 잘못된 방법 - 비율이 깨질 수 있음
2
VideoPlayer(_controller)
3

4
// 올바른 방법 - 비율 유지
5
AspectRatio(
6
  aspectRatio: _controller.value.aspectRatio,
7
  child: VideoPlayer(_controller),
8
)
_controller.value.aspectRatio는 초기화 후에만 올바른 값을 반환합니다. 초기화 전에는 1.0을 반환합니다.

결론: FutureBuilder로 초기화 상태를 확인하고, AspectRatio로 비율을 유지하면서 VideoPlayer를 표시합니다.

챕터 4: 재생 컨트롤 구현#

Why#

NOTE
사용자가 비디오를 제어하려면 재생/일시정지, 탐색, 볼륨 조절 등의 컨트롤이 필요합니다.
VideoPlayerController의 메서드로 이러한 기능을 구현합니다.
1
play() → 재생 시작
2
pause() → 일시정지
3
seekTo() → 특정 위치로 이동
4
setVolume() → 볼륨 조절
5
setLooping() → 반복 재생

What#

NOTE
VideoPlayerController는 재생 상태와 메타데이터를 VideoPlayerValue로 제공합니다.
isPlaying, position, duration 등의 속성으로 현재 상태를 확인할 수 있습니다.

How#

TIP

재생/일시정지 버튼

1
Scaffold(
2
  body: FutureBuilder(
3
    future: _initializeVideoPlayerFuture,
4
    builder: (context, snapshot) {
5
      if (snapshot.connectionState == ConnectionState.done) {
6
        return AspectRatio(
7
          aspectRatio: _controller.value.aspectRatio,
8
          child: VideoPlayer(_controller),
9
        );
10
      }
11
      return const Center(child: CircularProgressIndicator());
12
    },
13
  ),
14
  floatingActionButton: FloatingActionButton(
15
    onPressed: () {
16
      setState(() {
17
        if (_controller.value.isPlaying) {
18
          _controller.pause();
19
        } else {
20
          _controller.play();
21
        }
22
      });
23
    },
24
    child: Icon(
25
      _controller.value.isPlaying ? Icons.pause : Icons.play_arrow,
26
    ),
27
  ),
28
)

진행률 표시기와 탐색

1
Column(
2
  children: [
3
    AspectRatio(
4
      aspectRatio: _controller.value.aspectRatio,
5
      child: VideoPlayer(_controller),
6
    ),
7
    VideoProgressIndicator(
8
      _controller,
9
      allowScrubbing: true,  // 드래그로 탐색 허용
10
      colors: const VideoProgressColors(
11
        playedColor: Colors.blue,
12
        bufferedColor: Colors.grey,
13
        backgroundColor: Colors.black26,
14
      ),
15
    ),
16
  ],
17
)

커스텀 컨트롤 바

1
class VideoControlBar extends StatelessWidget {
2
  final VideoPlayerController controller;
3

4
  const VideoControlBar({super.key, required this.controller});
5

6
  @override
7
  Widget build(BuildContext context) {
8
    return ValueListenableBuilder<VideoPlayerValue>(
9
      valueListenable: controller,
10
      builder: (context, value, child) {
11
        return Row(
12
          children: [
13
            // 재생/일시정지
14
            IconButton(
15
              icon: Icon(value.isPlaying ? Icons.pause : Icons.play_arrow),
16
              onPressed: () {
17
                value.isPlaying ? controller.pause() : controller.play();
18
              },
19
            ),
20
            // 현재 시간
21
            Text(_formatDuration(value.position)),
22
            // 진행률 바
23
            Expanded(
24
              child: Slider(
25
                value: value.position.inMilliseconds.toDouble(),
26
                min: 0,
27
                max: value.duration.inMilliseconds.toDouble(),
28
                onChanged: (newValue) {
29
                  controller.seekTo(Duration(milliseconds: newValue.toInt()));
30
                },
31
              ),
32
            ),
33
            // 전체 시간
34
            Text(_formatDuration(value.duration)),
35
            // 볼륨
36
            IconButton(
37
              icon: Icon(value.volume > 0 ? Icons.volume_up : Icons.volume_off),
38
              onPressed: () {
39
                controller.setVolume(value.volume > 0 ? 0 : 1);
40
              },
41
            ),
42
          ],
43
        );
44
      },
45
    );
46
  }
47

48
  String _formatDuration(Duration duration) {
49
    final minutes = duration.inMinutes.remainder(60).toString().padLeft(2, '0');
50
    final seconds = duration.inSeconds.remainder(60).toString().padLeft(2, '0');
51
    return '$minutes:$seconds';
52
  }
53
}

Watch out#

WARNING

setState()를 자주 호출하면 성능이 저하됩니다.
재생 중에 매 프레임마다 위치를 업데이트하면 비효율적입니다.

1
// 비효율적 - 매 프레임 setState
2
_controller.addListener(() {
3
  setState(() {}); // 전체 위젯 리빌드
4
});
5

6
// 효율적 - ValueListenableBuilder 사용
7
ValueListenableBuilder<VideoPlayerValue>(
8
  valueListenable: _controller,
9
  builder: (context, value, child) {
10
    return Text('${value.position}');  // 해당 부분만 리빌드
11
  },
12
)

결론: VideoPlayerController의 메서드로 재생을 제어하고, ValueListenableBuilder로 효율적으로 UI를 업데이트합니다.

챕터 5: Chewie로 완성된 UI 구현#

Why#

NOTE
직접 컨트롤 UI를 만드는 것은 시간이 많이 걸립니다.
chewie 패키지는 Material/Cupertino 스타일의 완성된 비디오 플레이어 UI를 제공합니다.
1
video_player → 비디오 재생 기능
2
chewie → 완성된 컨트롤 UI

What#

NOTE
Chewie는 video_player 위에 구축된 UI 패키지입니다.
재생 버튼, 진행률 바, 전체 화면 전환, 자막 등을 기본 제공합니다.

How#

TIP

패키지 설치

1
flutter pub add chewie

기본 사용법

1
import 'package:chewie/chewie.dart';
2
import 'package:video_player/video_player.dart';
3

4
class ChewieVideoPlayer extends StatefulWidget {
5
  const ChewieVideoPlayer({super.key});
6

7
  @override
8
  State<ChewieVideoPlayer> createState() => _ChewieVideoPlayerState();
9
}
10

11
class _ChewieVideoPlayerState extends State<ChewieVideoPlayer> {
12
  late VideoPlayerController _videoPlayerController;
13
  ChewieController? _chewieController;
14

15
  @override
16
  void initState() {
17
    super.initState();
18
    _initializePlayer();
19
  }
20

21
  Future<void> _initializePlayer() async {
22
    _videoPlayerController = VideoPlayerController.networkUrl(
23
      Uri.parse(
24
        'https://flutter.github.io/assets-for-api-docs/assets/videos/butterfly.mp4',
25
      ),
26
    );
27

28
    await _videoPlayerController.initialize();
29

30
    _chewieController = ChewieController(
31
      videoPlayerController: _videoPlayerController,
32
      autoPlay: true,
33
      looping: true,
34
    );
35

36
    setState(() {});
37
  }
38

39
  @override
40
  void dispose() {
41
    _videoPlayerController.dispose();
42
    _chewieController?.dispose();
43
    super.dispose();
44
  }
45

46
  @override
47
  Widget build(BuildContext context) {
48
    return Scaffold(
49
      appBar: AppBar(title: const Text('Chewie 플레이어')),
50
      body: Center(
51
        child: _chewieController != null &&
52
                _chewieController!.videoPlayerController.value.isInitialized
53
            ? Chewie(controller: _chewieController!)
54
            : const CircularProgressIndicator(),
55
      ),
56
    );
57
  }
58
}

ChewieController 옵션

1
_chewieController = ChewieController(
2
  videoPlayerController: _videoPlayerController,
3
  autoPlay: false,           // 자동 재생
4
  looping: true,             // 반복 재생
5
  aspectRatio: 16 / 9,       // 비율 고정
6
  autoInitialize: true,      // 자동 초기화
7
  showControls: true,        // 컨트롤 표시
8
  showOptions: true,         // 설정 메뉴 표시
9
  allowFullScreen: true,     // 전체 화면 허용
10
  allowMuting: true,         // 음소거 허용
11
  allowPlaybackSpeedChanging: true,  // 재생 속도 변경
12
  playbackSpeeds: [0.5, 1.0, 1.5, 2.0],
13
  materialProgressColors: ChewieProgressColors(
14
    playedColor: Colors.red,
15
    handleColor: Colors.red,
16
    backgroundColor: Colors.grey,
17
    bufferedColor: Colors.white54,
18
  ),
19
);

Watch out#

WARNING
Chewie를 사용할 때 VideoPlayerController와 ChewieController 둘 다 dispose해야 합니다.
1
@override
2
void dispose() {
3
  _videoPlayerController.dispose();  // 먼저 비디오 컨트롤러
4
  _chewieController?.dispose();      // 그 다음 Chewie 컨트롤러
5
  super.dispose();
6
}
autoInitialize: true를 설정하면 별도로 initialize()를 호출할 필요가 없지만, 초기화 완료 시점을 정확히 알기 어렵습니다.

결론: Chewie를 사용하면 완성된 비디오 플레이어 UI를 쉽게 구현할 수 있습니다.

챕터 6: 자막과 추가 기능#

Why#

NOTE
비디오에 자막을 추가하면 접근성이 향상됩니다.
Chewie는 자막, 재생 속도 변경, 커스텀 옵션 등을 지원합니다.
1
자막 → 청각 장애인 지원, 다국어 지원
2
재생 속도 → 학습 영상에서 유용
3
커스텀 옵션 → 화질 선택 등

What#

NOTE
Subtitle 클래스로 시작 시간, 종료 시간, 텍스트를 정의합니다.
ChewieController의 subtitle 속성에 자막 목록을 전달합니다.

How#

TIP

자막 추가

1
_chewieController = ChewieController(
2
  videoPlayerController: _videoPlayerController,
3
  autoPlay: true,
4
  subtitle: Subtitles([
5
    Subtitle(
6
      index: 0,
7
      start: Duration.zero,
8
      end: const Duration(seconds: 5),
9
      text: '안녕하세요, Flutter 비디오 튜토리얼입니다.',
10
    ),
11
    Subtitle(
12
      index: 1,
13
      start: const Duration(seconds: 5),
14
      end: const Duration(seconds: 10),
15
      text: '이 영상에서는 비디오 재생 방법을 배웁니다.',
16
    ),
17
    Subtitle(
18
      index: 2,
19
      start: const Duration(seconds: 10),
20
      end: const Duration(seconds: 15),
21
      text: '시작해볼까요?',
22
    ),
23
  ]),
24
  showSubtitles: true,  // 자막 기본 표시
25
  subtitleBuilder: (context, subtitle) {
26
    return Container(
27
      padding: const EdgeInsets.all(8),
28
      decoration: BoxDecoration(
29
        color: Colors.black54,
30
        borderRadius: BorderRadius.circular(4),
31
      ),
32
      child: Text(
33
        subtitle,
34
        style: const TextStyle(
35
          color: Colors.white,
36
          fontSize: 16,
37
        ),
38
      ),
39
    );
40
  },
41
);

커스텀 옵션 추가

1
_chewieController = ChewieController(
2
  videoPlayerController: _videoPlayerController,
3
  additionalOptions: (context) {
4
    return [
5
      OptionItem(
6
        onTap: () => _showQualityDialog(context),
7
        iconData: Icons.high_quality,
8
        title: '화질 선택',
9
      ),
10
      OptionItem(
11
        onTap: () => _downloadVideo(),
12
        iconData: Icons.download,
13
        title: '다운로드',
14
      ),
15
    ];
16
  },
17
);

SRT 파일에서 자막 로드

1
Future<Subtitles> _loadSubtitlesFromSrt(String srtPath) async {
2
  final srtContent = await rootBundle.loadString(srtPath);
3
  final subtitles = <Subtitle>[];
4

5
  final blocks = srtContent.split('\n\n');
6
  for (var i = 0; i < blocks.length; i++) {
7
    final lines = blocks[i].split('\n');
8
    if (lines.length >= 3) {
9
      final times = lines[1].split(' --> ');
10
      subtitles.add(Subtitle(
11
        index: i,
12
        start: _parseSrtTime(times[0]),
13
        end: _parseSrtTime(times[1]),
14
        text: lines.sublist(2).join('\n'),
15
      ));
16
    }
17
  }
18

19
  return Subtitles(subtitles);
20
}
21

22
Duration _parseSrtTime(String time) {
23
  final parts = time.split(':');
24
  final seconds = parts[2].split(',');
25
  return Duration(
26
    hours: int.parse(parts[0]),
27
    minutes: int.parse(parts[1]),
28
    seconds: int.parse(seconds[0]),
29
    milliseconds: int.parse(seconds[1]),
30
  );
31
}

Watch out#

WARNING

자막 타이밍이 정확하지 않으면 사용자 경험이 나빠집니다.
비디오와 자막 시간을 정확히 맞춰야 합니다.

1
// 자막 시작/종료 시간이 겹치지 않도록 주의
2
Subtitle(
3
  index: 0,
4
  start: Duration.zero,
5
  end: const Duration(seconds: 5),  // 5초에서 끝
6
  text: '첫 번째 자막',
7
),
8
Subtitle(
9
  index: 1,
10
  start: const Duration(seconds: 5),  // 5초에서 시작 (겹치지 않음)
11
  end: const Duration(seconds: 10),
12
  text: '두 번째 자막',
13
),

결론: Chewie의 자막과 추가 옵션 기능을 활용하면 전문적인 비디오 플레이어를 구현할 수 있습니다.

한계#

Flutter의 video_player는 대부분의 상황을 처리하지만 몇 가지 제약이 있습니다.

플랫폼 지원: Linux와 Windows는 지원하지 않습니다.
DRM 미지원: 기본 패키지는 DRM 보호 콘텐츠를 재생할 수 없습니다.
코덱 제한: 플랫폼별로 지원하는 코덱이 다릅니다.
백그라운드 재생: 기본적으로 백그라운드 재생을 지원하지 않습니다.
스트리밍 제한: HLS/DASH 스트리밍은 플랫폼별 지원이 다릅니다.

video_player: Flutter에서 비디오를 재생하는 공식 플러그인이다. iOS의 AVPlayer와 Android의 ExoPlayer를 사용한다. ↩
chewie: video_player 위에 구축된 UI 패키지로, Material/Cupertino 스타일의 완성된 플레이어 UI를 제공한다. ↩
VideoPlayerController: 비디오 소스를 로드하고 재생을 제어하는 컨트롤러 클래스다. ↩

Flutter 튜토리얼 21편: 비디오 재생

요약#

핵심 요지#

문서가 설명하는 범위#

참고 자료#

문제 상황#

비디오 재생의 어려움#

해결 방법#

챕터 1: video_player 설정하기#

Why#

What#

How#

Watch out#

챕터 2: VideoPlayerController 초기화#

Why#

What#

How#

Watch out#

챕터 3: 비디오 화면에 표시하기#

Why#

What#

How#

Watch out#

챕터 4: 재생 컨트롤 구현#

Why#

What#

How#

Watch out#

챕터 5: Chewie로 완성된 UI 구현#

Why#

What#

How#

Watch out#

챕터 6: 자막과 추가 기능#

Why#

What#

How#

Watch out#

한계#

Footnotes#

공유

목차