로컬 자체 호스팅 오디오 변환·편집 도구 - Audio Toolkit

Python + FastAPI + Uvicorn + FFmpeg 기반의 로컬 자체 호스팅 오디오 변환·편집 도구로, 별도의 웹 서버나 외부 데이터베이스 없이 자신의 PC에서 직접 실행할 수 있는 오픈소스 프로젝트.

2026-11-18 (수) 18:42:12 조회 9
문의하기
로컬 자체 호스팅 오디오 변환·편집 도구 - Audio Toolkit
Python FastAPI Uvicorn Pydantic FFmpeg FFprobe HTML5 CSS3 Vanilla JavaScript JSON Server-Sent Events (SSE)

Nginx·Apache 등 별도의 웹 서버 없이, Python + FastAPI + Uvicorn + FFmpeg만으로 자신의 PC에서 오디오를 변환하고 편집하자!

외부 온라인 오디오 변환 서비스에 파일을 업로드하지 않고, 자신의 PC(Linux·Windows·macOS)에서 직접 오디오 파일을 변환하고 편집할 수 있도록 개발한 로컬 자체 호스팅(Self-hosting) 오디오 처리 도구입니다.

별도의 Nginx·Apache 웹 서버, Docker, 외부 데이터베이스 없이 Python 가상환경과 FFmpeg만으로 실행할 수 있습니다.

특히 개발 환경과 일반 로컬 실행 환경에서 동일한 Python + FastAPI + Uvicorn 구조를 사용하도록 구성했습니다.

웹 브라우저에서 오디오 파형을 확인하고, 원하는 구간을 선택하여 자르거나 제거하고, 여러 파일을 병합하거나 다양한 오디오 형식으로 변환할 수 있습니다.


1. 프로젝트 정보

  • 프로젝트: Audio Toolkit
  • 버전: v1.0.0 — Initial Public Release
  • 백엔드: Python + FastAPI + Uvicorn
  • 오디오 처리: FFmpeg + FFprobe
  • 프런트엔드: HTML5 + CSS3 + Vanilla JavaScript
  • 데이터베이스: 별도 DB 불필요
  • 운영 환경: Linux, Windows 10/11, macOS
  • Python: 3.11 이상 권장
  • 라이선스: MIT

GitHub 저장소

https://github.com/glitter-node/audio-toolkit

v1.0.0 공식 릴리스

https://github.com/glitter-node/audio-toolkit/releases/tag/v1.0.0


2. 주요 기능

오디오 형식 변환

다양한 오디오 파일을 원하는 출력 형식으로 변환할 수 있습니다.

지원 입력 형식

MP3, WAV, M4A, AAC, FLAC, OGG, Opus, WebM

지원 출력 형식

MP3, WAV, FLAC, OGG, Opus, M4A

입력 파일은 FFprobe를 통해 실제 오디오 스트림이 있는지 확인하며, 변환 작업은 서버에서 FFmpeg로 처리합니다.

실제 지원 코덱과 인코딩 기능은 설치된 FFmpeg 환경에 따라 달라질 수 있습니다.

오디오 파형 편집

브라우저에 표시되는 오디오 파형(Waveform)을 이용하여 편집할 수 있습니다.

  • 오디오 파형 시각화
  • 타임라인과 재생 위치 표시
  • 파형 확대 및 축소
  • 원하는 위치로 이동
  • 드래그를 통한 구간 선택
  • 선택 구간 반복 재생
  • 선택 경계 조정

파형을 확인하면서 원하는 구간을 직접 선택할 수 있어 별도의 전문 오디오 편집 프로그램 없이도 기본적인 편집 작업이 가능합니다.

오디오 자르기 및 구간 제거

Trim

선택한 구간만 추출하여 새로운 오디오 파일로 저장합니다.

Remove

선택한 구간을 제거하고 앞뒤 오디오를 연결합니다.

구간 제거 시 연결 지점의 부자연스러운 소리를 줄이기 위해 크로스페이드(Crossfade)를 적용할 수 있습니다.

지원 크로스페이드 설정은 0ms, 10ms, 20ms, 50ms, 100ms이며 기본 선택값은 20ms입니다.

실제 적용되는 길이는 오디오의 구간 길이와 경계 조건에 따라 조정될 수 있습니다.

여러 오디오 파일 병합

여러 오디오 파일을 하나의 파일로 연결할 수 있습니다.

현재 버전에서는 2~10개의 서로 다른 파일을 병합할 수 있습니다.

녹음 파일이나 분할된 오디오를 하나로 연결할 때 활용할 수 있습니다.

음량 및 페이드 효과

오디오의 음량을 조절하고 페이드 인(Fade-in), 페이드 아웃(Fade-out) 효과를 적용할 수 있습니다.

편집 이력 및 결과 재사용

  • Undo / Redo 지원
  • 최근 처리 결과 확인
  • 처리 결과 미리 듣기
  • 결과 파일 다운로드
  • 처리된 오디오를 다시 불러와 추가 편집

백그라운드 작업 처리

FFmpeg 작업은 백그라운드에서 실행됩니다.

Server-Sent Events(SSE)를 이용해 작업 상태와 진행 상황을 확인할 수 있으며, 진행 중인 작업을 취소할 수도 있습니다.

다국어 및 테마

지원 언어

한국어, 영어, 일본어, 중국어 간체

지원 테마

Light, Dark, System

사용자의 화면 환경에 맞춰 인터페이스를 사용할 수 있습니다.


3. 다운로드

공식 릴리스 페이지:

https://github.com/glitter-node/audio-toolkit/releases/tag/v1.0.0

ZIP 다운로드

https://github.com/glitter-node/audio-toolkit/releases/download/v1.0.0/audio-toolkit-v0.1.0.zip

TAR.GZ 다운로드

https://github.com/glitter-node/audio-toolkit/releases/download/v1.0.0/audio-toolkit-v0.1.0.tar.gz

참고로 공식 릴리스 태그는 v1.0.0이지만, 현재 배포된 압축파일 이름에는 기존 v0.1.0이 유지되어 있습니다.

압축파일을 해제한 후 app/main.py, requirements.txt, .env.example 파일이 있는 디렉터리를 프로젝트 루트로 사용하면 됩니다.


4. Linux 설치 및 실행 방법

Ubuntu 또는 Debian 계열 환경을 기준으로 설명합니다.

① Python 및 FFmpeg 준비

sudo apt update
sudo apt install python3 python3-venv python3-pip ffmpeg

② GitHub 저장소 복제

git clone https://github.com/glitter-node/audio-toolkit.git
cd audio-toolkit

③ Python 가상환경 생성

python3 -m venv .venv

④ 패키지 설치

.venv/bin/python -m pip install -r requirements.txt

⑤ Audio Toolkit 실행

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8012

⑥ 웹 브라우저 접속

http://127.0.0.1:8012/

위 주소에 접속하면 Audio Toolkit 웹 인터페이스를 사용할 수 있습니다.

설치된 Python 버전은 3.11 이상이어야 하며, ffmpeg -version 및 ffprobe -version 명령으로 두 프로그램의 설치 상태를 각각 확인하는 것이 좋습니다.


5. Windows 10/11 설치 및 실행 방법

Windows에서는 Python 3.11 이상과 FFmpeg를 먼저 설치합니다.

FFmpeg의 bin 디렉터리가 PATH에 등록되어 있어야 합니다.

PowerShell에서 다음 명령으로 확인합니다.

py --list
ffmpeg -version
ffprobe -version

① 프로젝트 다운로드

GitHub 릴리스 페이지에서 ZIP 파일을 다운로드하여 원하는 디렉터리에 압축을 해제합니다.

② PowerShell에서 프로젝트 디렉터리 이동

Set-Location (Read-Host "Enter the full path to the Audio Toolkit project")

③ 가상환경 생성

py -3.11 -m venv .venv

④ 패키지 설치

& .\.venv\Scripts\python.exe -m pip install -r requirements.txt

⑤ 서버 실행

& .\.venv\Scripts\python.exe -m uvicorn app.main:app --host 127.0.0.1 --port 8012

⑥ 웹 브라우저 접속

http://127.0.0.1:8012/

PowerShell 실행 정책을 변경하거나 가상환경 활성화 스크립트를 실행하지 않아도 가상환경의 Python 실행 파일을 직접 호출할 수 있습니다.

Windows 로그인 시 자동 시작

Windows 작업 스케줄러(Task Scheduler)를 이용하면 사용자 로그인 시 Audio Toolkit이 자동으로 실행되도록 설정할 수 있습니다.

별도의 Windows 서비스 프로그램이나 Docker를 설치할 필요가 없습니다.

자세한 설정 방법은 다음 문서를 참고하면 됩니다.

https://github.com/glitter-node/audio-toolkit/blob/main/docs/WINDOWS_AUTOSTART.md


6. macOS 설치 및 실행 방법

Intel Mac과 Apple Silicon Mac에서 사용할 수 있도록 설치 절차를 제공합니다.

Python 3.11 이상과 해당 시스템에 맞는 FFmpeg가 필요합니다.

Homebrew가 설치되어 있다면 다음 명령으로 FFmpeg를 설치할 수 있습니다.

brew install ffmpeg

프로젝트 다운로드

git clone https://github.com/glitter-node/audio-toolkit.git
cd audio-toolkit

가상환경 생성 및 패키지 설치

python3 -m venv .venv
.venv/bin/python -m pip install -r requirements.txt

서버 실행

.venv/bin/python -m uvicorn app.main:app --host 127.0.0.1 --port 8012

브라우저 접속

http://127.0.0.1:8012/

Apple Silicon에서는 가능하면 ARM64 환경에 맞는 Python과 FFmpeg를 사용하는 것이 좋습니다.

macOS의 세부 코덱 호환성은 설치된 패키지와 시스템 환경에 따라 달라질 수 있습니다.


7. Audio Toolkit 사용 방법

설치와 실행을 완료하면 웹 브라우저에서 오디오 편집 작업을 진행할 수 있습니다.

① 오디오 파일 업로드

Audio Toolkit에 접속한 후 변환하거나 편집할 오디오 파일을 선택합니다.

업로드한 파일은 FFprobe를 통해 분석되며 오디오 메타데이터와 재생 시간 등을 확인할 수 있습니다.

② 파형 확인

파일을 불러오면 오디오 파형이 표시됩니다.

재생 버튼으로 오디오를 미리 듣거나, 타임라인을 이동하고 파형을 확대하여 원하는 구간을 확인할 수 있습니다.

③ 편집 구간 선택

파형에서 원하는 구간을 드래그하여 선택합니다.

선택 경계를 조절하거나 선택한 구간을 반복 재생하면서 편집 범위를 확인합니다.

④ 편집 기능 실행

작업 목적에 따라 기능을 선택합니다.

  • Convert: 다른 오디오 형식으로 변환
  • Trim: 선택한 구간만 추출
  • Remove: 선택한 구간 제거
  • Merge: 여러 오디오 파일 병합
  • Volume: 음량 조절
  • Fade: 페이드 인·아웃 적용

⑤ 처리 진행 상황 확인

작업을 실행하면 서버에서 FFmpeg가 오디오를 처리합니다.

SSE를 통해 작업 상태를 확인할 수 있으며 필요한 경우 취소할 수 있습니다.

⑥ 결과 확인 및 다운로드

작업이 완료되면 처리된 오디오를 미리 듣고 다운로드할 수 있습니다.

필요하다면 처리 결과를 다시 편집기로 불러와 추가 편집을 진행할 수 있습니다.


8. 활용 사례

음악 파일 변환

FLAC 파일을 MP3로 변환하거나, 호환성이 필요한 환경에 맞게 오디오 형식을 변경할 수 있습니다.

녹음 파일 편집

강의, 회의 또는 개인 녹음 파일에서 불필요한 앞뒤 구간이나 중간 부분을 제거할 수 있습니다.

여러 녹음 파일 병합

분할된 오디오 파일을 하나의 파일로 연결할 수 있습니다.

오디오 음량 조절

음량을 조정하거나 시작과 끝부분에 페이드 효과를 적용할 수 있습니다.

반복 편집

처리된 오디오를 다시 불러와 추가로 자르거나 변환할 수 있습니다.

단, 손실 압축 오디오를 반복해서 재인코딩하면 음질이 저하될 수 있으므로 중간 편집에는 WAV나 FLAC 같은 형식을 고려하는 것이 좋습니다.


9. 로컬 자체 호스팅의 특징

Audio Toolkit은 외부 오디오 변환 플랫폼에 의존하지 않고 자신의 PC 또는 자체 서버에서 오디오를 처리하는 것을 목표로 합니다.

일반적인 로컬 사용 환경에서는 다음과 같은 구성이 가능합니다.

  • Python 가상환경
  • FastAPI 애플리케이션
  • Uvicorn 웹 서버
  • FFmpeg 및 FFprobe
  • 웹 브라우저

Nginx, Apache, Docker 또는 외부 데이터베이스가 필수 구성 요소는 아닙니다.

다만 원격 접속이 필요한 서버 환경에서는 기존 Nginx나 Apache를 리버스 프록시로 연결하여 운영할 수도 있습니다.

파일 저장과 보안

Audio Toolkit은 오디오 파일을 로컬에서 처리하지만, 업로드한 파일과 처리 결과는 호스트의 저장소에 임시 보관됩니다.

기본 데이터 디렉터리는 ./data이며, 기본 파일 보관 기간은 24시간입니다.

정리 작업은 약 5분 간격으로 실행됩니다.

현재 버전에는 사용자 인증과 사용자별 파일 격리 기능이 내장되어 있지 않으므로, 외부 네트워크에 직접 공개하는 방식은 권장하지 않습니다.

원격으로 사용할 경우 HTTPS, 인증, 접근 제어, 업로드 제한 및 요청 제한 등을 별도로 구성해야 합니다.

HTTP 보안 헤더와 Content Security Policy(CSP) 설정도 지원합니다.


10. v1.0.0의 현재 제한 사항

첫 공식 공개 버전인 만큼 다음 사항을 참고해 주세요.

  • 출력 비트레이트와 샘플레이트를 직접 지정하는 기능은 제공하지 않습니다.
  • 브라우저 파형 디코딩에는 64MB 제한이 적용됩니다.
  • 기본 업로드 용량 제한은 200MB입니다.
  • FFmpeg 작업자는 하나이며 대기·실행 중인 작업은 최대 8개까지 허용합니다.
  • 작업 상태는 프로세스 메모리에 저장되므로 서버를 재시작하면 상태 정보가 사라집니다.
  • 사용 가능한 인코더와 코덱은 설치된 FFmpeg 빌드에 따라 달라집니다.
  • Windows 및 macOS 환경에서는 설치 구성에 따라 추가 검증이 필요할 수 있습니다.
  • 현재 버전에는 음성 인식(STT) 기능이 연결되어 있지 않습니다.

11. 소스 코드 및 문서

GitHub Repository
Official Release v1.0.0
README / Installation Guide
Windows Auto-Start Guide
AI Agent / Contributor Guidelines
GitHub Issues


마치며

Audio Toolkit은 단순한 온라인 오디오 변환 서비스가 아니라, 자신의 PC에서 직접 설치하고 운영할 수 있는 로컬 자체 호스팅 오디오 변환·편집 도구를 목표로 개발했습니다.

특히 Python + FastAPI + Uvicorn 조합을 통해 개발 환경과 일반 로컬 실행 환경의 일관성을 유지하고, 별도의 웹 서버나 복잡한 인프라 없이 브라우저 기반 오디오 편집 기능을 사용할 수 있도록 구성했습니다.

Linux, Windows, macOS 환경에서 사용할 수 있도록 설치 문서를 제공하고 있으며, 소스 코드는 MIT 라이선스로 공개했습니다.

아직 첫 공식 공개 버전이므로 사용 환경에 따라 부족하거나 개선이 필요한 부분이 있을 수 있습니다.

직접 사용해 보시고 오류나 개선 의견이 있다면 GitHub Issues를 통해 알려주시면 감사하겠습니다.

Audio Toolkit v1.0.0 — Initial Public Release

https://github.com/glitter-node/audio-toolkit


댓글 (0)

로그인 후 댓글을 남길 수 있습니다.
아직 댓글이 없습니다. 첫 번째 댓글을 남겨보세요!