[FFmpeg] FFmpeg 7.1 + H.265(libx265) 지원 정적 빌드

[FFmpeg] FFmpeg 7.1 + H.265(libx265) 지원 정적 빌드 – 기존 MinGW64 환경 확장

쿼드큐브 2025. 11. 5. 13:38

[FFmpeg] FFmpeg 7.1 + H.265(libx265) 지원 정적 빌드 – 기존 MinGW64 환경 확장

"본 글은 과거 티스토리에서 발행했던 콘텐츠를 기반으로, 최신 정보를 반영해 새롭게 정리한 업데이트 버전입니다."

📚 목차
1. 목표 및 환경 개요: FFmpeg 정적빌드 + H.265 지원
2. 패키지 설치 실패 원인 분석: mingw-w64-x86_64-x265와 버전 충돌
3. libx265 4.0 직접 빌드: 정적 라이브러리로 컴파일하기
4. FFmpeg 7.1 정적 빌드: libx265 포함 구성 및 설치
5. 정적 링크 오류 해결: x265.pc 수정으로 DLL 종속 제거
6. 정상 빌드 확인 및 H.265 스트리밍 인코딩 테스트
✔ 마무리

1. 목표 및 환경 개요: FFmpeg 정적 빌드 + H.265 지원

본 문서에서는 Windows 10 환경에서 MinGW-w64 툴체인을 사용하여 FFmpeg 7.1을 정적으로(static) 빌드하고, H.265(HEVC) 인코딩을 지원하는 ffmpeg.exe를 생성하는 과정을 다룹니다.

정적 빌드란, 실행 파일이 외부 DLL에 의존하지 않고 필요한 라이브러리를 내부에 포함하는 방식을 의미합니다. 이는 다음과 같은 장점이 있습니다:

▸ 배포 환경에 DLL 설치 없이도 실행 가능
▸ 라이브러리 충돌 없이 독립적 실행 가능
▸ 보안/버전 관리 측면에서 안정성 증가

FFmpeg 공식 소스는 libx265를 통한 H.265 인코딩을 지원하지만, MinGW 환경에서는 libx265 패키지 호환성 문제가 발생할 수 있습니다. 이에 따라 본 글에서는 libx265를 직접 빌드하여 정적으로 연결하는 방법을 실습합니다.

2. 패키지 설치 실패 원인 분석: mingw-w64-x86_64-x265와 버전 충돌

처음에는 MinGW 패키지 매니저(pacman)를 이용해 libx265를 설치하고 FFmpeg를 빌드하려 했습니다.

pacman -S mingw-w64-x86_64-x265

설치는 정상적으로 진행되었지만, 빌드 과정에서 아래와 같은 문제가 발생했습니다:
▸ pacman을 통해 설치되는 x265는 버전 4.1.2

▸ FFmpeg 7.1 소스코드는 x265 4.0과의 API 구조를 기준으로 작성됨

이로 인해 libavcodec/libx265.c에서 컴파일 에러 발생

mingw-w64-x86_64-x265 관련 ffmpeg 컴파일 오류 메세지 화면

예를 들어, FFmpeg의 소스 코드에는 다음과 같은 조건 분기 코드가 존재합니다

#if X265_BUILD >= 210
    for (i = 0; i < MAX_SCALABLE_LAYERS; i++)
        x265pic_lyrptr_out[i] = &x265pic_layers_out[i];

    ret = ctx->api->encoder_encode(ctx->encoder, &nal, &nnal,
/* 주석처리         pic ? &x265pic : NULL, x265pic_lyrptr_out);  */
/* 코드 추가 */	    pic ? &x265pic : NULL, x265pic_lyrptr_out ? *x265pic_lyrptr_out : NULL);

#else
    ret = ctx->api->encoder_encode(ctx->encoder, &nal, &nnal,
                                   pic ? &x265pic : NULL, &x265pic_solo_out);
#endif

libx265의 내부 구조가 변경되면서 포인터 타입이 달라졌고, 직접 소스를 수정하거나 libx265를 적절한 버전으로 빌드해야 합니다.

3. libx265 4.0 직접 빌드: 정적 라이브러리로 컴파일하기

패키지 설치로는 해결되지 않으므로, libx265를 직접 4.0 버전으로 소스 빌드합니다

1. home 경로로 이동
cd
/home/ubuntu

2. git에서 소스 복제하기
git clone https://bitbucket.org/multicoreware/x265_git.git

3. 소스 경로로 이동
cd x265_git

4. 4.0 버전 전환 
git checkout 4.0

x265는 CMake 프로젝트이며, 빌드는 /build 디렉토리에서 진행합니다.

1. build 경로로 이동
cd build

// 다시빌드할 경우 build 경로를 삭제하고 재 생성하여 작업하면 됩니다.
// rm -rf build
// mkdir build
// cd build

2. cmake로 static 빌드 설정
cmake -G Ninja \
    -DCMAKE_INSTALL_PREFIX=/mingw64 \
    -DENABLE_SHARED=off \
    -DCMAKE_EXE_LINKER_FLAGS="-static -static-libgcc -static-libstdc++" \
    ../source
    
3. 컴파일 & 링크
ninja
ninja install

TIP: 재빌드 시에는 rm -rf build && mkdir build로 깨끗하게 초기화하세요.

✔️ 빌드 결과 확인

ldd /mingw64/bin/x265.exe를 실행해 외부 DLL이 없는지 확인합니다.

시스템 기본 라이브러리 외에 의존성 없는 상태라면 정적 빌드 성공입니다.

4. FFmpeg 7.1 정적 빌드: libx265 포함 구성 및 설치

libx265를 정적으로 준비했으므로 이제 FFmpeg를 정적으로 빌드합니다.

cd ~/ffmpeg

./configure --prefix=/home/ubuntu/dist \
  --arch=x86_64 \
  --enable-static \
  --disable-shared \
  --disable-debug \
  --disable-doc \
  --enable-gpl \
  --enable-version3 \
  --enable-nonfree \
  --enable-libx264 \
  --enable-libx265 \
  --enable-libwebp \
  --enable-libvpx \
  --enable-libfdk-aac \
  --enable-libvorbis \
  --enable-libmp3lame \
  --enable-libopus \
  --enable-openssl \
  --disable-libass \
  --disable-iconv \
  --disable-autodetect \
  --disable-w32threads \
  --extra-cflags="-static -static-libgcc -static-libstdc++" \
  --extra-ldflags="-static -static-libgcc -static-libstdc++" \
  --pkg-config-flags="--static"

make -j$(nproc)
make install

빌드는 문제 없이 완료되지만, 다음 단계에서 중요한 링크 오류가 발생할 수 있습니다

5. 정적 링크 오류 해결: x265.pc 수정으로 DLL 종속 제거

FFmpeg를 정적(static)으로 빌드했다고 하더라도, 실제로 생성된 ffmpeg.exe를 검사해 보면 외부 DLL을 여전히 참조하는 경우가 종종 발생합니다.

이는 단순히 --enable-static 설정을 넣었다고 해서 자동으로 정적 링크가 완성되는 것이 아니라, 빌드 시스템 내부의 패키지 정보 처리 방식까지도 함께 조정해야 하기 때문입니다.

이런 출력은 정적 링크 실패를 의미하며, 배포 시에는 의존성 누락으로 실행 오류가 발생하게 됩니다.

pkgconfig/x265.pc 파일은
- pkg-config 도구가 libx265 라이브러리를 찾고 사용할 수 있도록 정보를 제공하는 메타데이터 파일입니다
- 보통 ./configure, Makefile, 또는 CMake 빌드 시스템에서 사용됩니다

🔷 해결 방법: x265.pc 수정하여 정적 링크 지시 추가

FFmpeg가 pkg-config를 통해 libx265를 정적으로 연결하도록 하기 위해서는, x265.pc 내부에 다음과 같은 정적 링크 지시 옵션을 추가해야 합니다.

1. x265 pkg-config 설정파일 열기
// 파일탐색기에서 해당파일을 열어 직접 편집해도 됩니다.
cd /mingw64/lib/pkgconfig
nano x265.pc

✔️ 수정전 x265.pc 파일내용 예

✔️ 수정후 x265.pc 파일내용 : Libs.private: -lstdc++ -static-libgcc -static-libstdc++ 추가

Libs.private 항목은 정적 링크 시에만 사용되는 내부 의존성 정보를 명시합니다.

특히 -lstdc++, -static-libgcc, -static-libstdc++는 MinGW 환경에서 반드시 정적으로 연결해야 할 핵심 라이브러리입니다.

✔️ 수정 후 재빌드

x265.pc 파일을 수정한 이후에는 FFmpeg를 반드시 깨끗한 상태에서 다시 빌드해야 합니다.

cd ~/ffmpeg
make distclean
./configure ...
make -j$(nproc)
make install

이제 ffmpeg.exe는 더 이상 외부 DLL을 참조하지 않고 완전히 정적으로 빌드됩니다.

6. 정상 빌드 확인 및 H.265 스트리밍 인코딩 테스트

정적 빌드의 가장 중요한 목적은 생성된 실행 파일(ffmpeg.exe)이 외부 DLL에 의존하지 않고, 하나의 단일 실행 파일로서 모든 기능을 수행할 수 있도록 하는 것입니다.

이를 검증하는 단계에서는 실제 실행 파일이 참조하는 동적 라이브러리를 확인하고, H.265 인코딩이 정상적으로 동작하는지 테스트해야 합니다.

cd /home/ubuntu/dist/bin
ldd ffmpeg.exe

Linux와 MinGW 환경에서는 ldd 명령을 통해 실행 파일이 의존하는 동적 라이브러리 목록을 확인할 수 있습니다.

cd ~/dist/bin
ldd ffmpeg.exe

▸ libx265.dll, libx264.dll, libfdk-aac.dll 등 외부 DLL이 출력에 존재하지 않아야 합니다.
▸ ntdll.dll, kernel32.dll, user32.dll 등은 Windows 기본 시스템 라이브러리이므로 괜찮습니다.

만약 여전히 외부 .dll 파일이 표시된다면 x265.pc 또는 다른 .pc 파일의 Libs.private 항목이 잘못 구성되어 있을 수 있습니다.

이 경우 5단계의 pkg-config 설정을 다시 점검하세요.

정적 링크가 완료되었더라도, 실제 H.265 인코딩 기능이 제대로 작동하는지를 테스트하는 것이 중요합니다. 이를 위해 libx265을 활용한 실전 스트리밍 인코딩 테스트를 수행합니다.

./ffmpeg.exe -i rtsp://example.com/stream \
  -c:v libx265 -c:a copy output.mp4

✔ 마무리

FFmpeg를 정적으로 빌드하면서 libx265를 안정적으로 포함하려면 단순한 옵션 설정만으로는 부족합니다.

빌드 환경과 라이브러리 버전, .pc 파일 설정까지 직접 제어해야 진정한 정적 빌드가 완성됩니다.

이번 과정을 템플릿화해 두면, 향후 다른 코덱 추가나 버전 업 시에도 안정적인 배포 환경을 반복적으로 구축할 수 있습니다.

정적 링크 품질은 결국 개발자가 얼마나 빌드 시스템을 정확히 이해하고 다루느냐에 달려 있습니다.

2. [FFmpeg] FFmpeg 7.1 + H.265(libx265) 지원 정적 빌드 – 기존 MinGW64 환경 확장

3. [FFmpeg] CUDA 가속 포함 FFmpeg 7.1 정적 빌드 – MinGW64 + libx264/x265 + NVENC

4. [FFmpeg] SHA-256 Digest 인증 대응 FFmpeg 7.1 정적 빌드 – MinGW64 + CUDA + 인증 로직 패치

5. [FFmpeg] RTSP 스트림을 fMP4로 변환해 초저지연 TCP 전송하기

6. [FFmpeg] 인코딩 실습: CPU(libx264)와 CUDA(h264_nvenc) 비교

※ 게시된 글 및 이미지 중 일부는 AI 도구의 도움을 받아 생성되거나 다듬어졌습니다.