n8n-nodes-mediafx
Version:
N8N custom nodes for video editing and media processing
307 lines (244 loc) • 13.6 kB
Markdown
# n8n-nodes-mediafx (한국어)
[](https://www.npmjs.com/package/n8n-nodes-mediafx)
[](https://opensource.org/licenses/MIT)
[](https://n8n.io)
이 저장소는 FFmpeg의 강력한 기능을 사용하여 포괄적인 로컬 미디어 처리를 위한 커스텀 n8n 노드를 포함하고 있습니다. 외부 API나 서비스 없이 n8n 워크플로우 내에서 직접 다양한 비디오, 오디오, 이미지, 텍스트 작업을 수행할 수 있습니다.
<!-- Optional: Add a GIF of the node in action here -->
<!-- <p align="center"><img src="link/to/your/demo.gif" alt="MediaFX Node Demo"></p> -->
## v1.4.2의 새로운 기능
- **버그 수정**: 비디오 소스가 올바르게 설정되지 않은 경우 오디오 분리 작업에서 "did not produce an output" 오류 수정
- 소스가 누락된 경우 명확한 오류 메시지와 함께 적절한 유효성 검사 추가
### v1.4.1
- **오디오 분리**: 비디오를 무음 비디오와 추출된 오디오 트랙으로 분리하는 새로운 Video 작업
- 사용자 정의 가능한 필드명으로 두 출력을 단일 아이템으로 반환
- 다양한 비디오 포맷(MP4, MOV, AVI, MKV) 및 오디오 포맷(MP3, AAC, WAV, FLAC) 지원
- 가장 빠른 처리를 위한 copy(재인코딩 없음) 포함 오디오 코덱 옵션
### v1.4.0
- **사용자 정의 출력 필드명**: 워크플로우 구성 개선을 위한 바이너리 출력 필드명 설정 가능
- **향상된 Merge 노드 지원**: 다중 입력 작업을 위한 n8n Merge 노드와의 원활한 연동
- **자동 해상도 처리**: 전환 효과에서 서로 다른 해상도의 비디오 스마트 스케일링
- **개선된 오류 메시지**: 상세한 바이너리 프로퍼티 정보로 더 나은 디버깅 지원
## MediaFX를 사용해야 하는 이유
- **프라이버시 중심**: 모든 처리가 n8n 인스턴스에서 로컬로 이루어집니다. 미디어 파일은 절대 서버 외부로 나가지 않습니다.
- **외부 API 불필요**: API 키, 구독, 제3자 서비스 비용이 필요 없습니다.
- **강력한 성능**: 고품질 미디어 조작을 위해 FFmpeg의 모든 기능을 활용합니다.
- **자체 포함**: `@ffmpeg-installer/ffmpeg`를 통해 FFmpeg가 자동으로 다운로드되고 포함되어, 대부분의 경우 시스템 종속성을 수동으로 설치할 필요가 없습니다.
- **유연성**: 간단한 자르기부터 복잡한 오디오 믹싱, 텍스트 오버레이까지 다양한 작업을 처리합니다.
## 주요 기능
- **비디오 처리**: 여러 클립 병합, 특정 구간 자르기, 자동 FFmpeg 호환성 감지로 비디오 간 전환 효과 적용, 단일 비디오에 페이드 인/아웃 효과 추가.
- **고급 오디오 조작**:
- 비디오에서 다양한 형식(MP3, WAV, AAC, FLAC)으로 오디오 추출
- 각 소스별 정밀한 볼륨 조절로 오디오 트랙 믹싱
- **부분 오디오 믹싱**: 시작 시간과 지속 시간을 조절하여 특정 시간 범위에 오디오 삽입
- **오디오 반복**: 짧은 오디오를 원하는 길이에 맞게 자동 반복
- **독립적인 페이드 효과**: 전체 믹싱과 부분 믹싱 모두에서 사용자 지정 길이로 페이드 인/아웃 효과 적용
- **고급 이미지 작업**:
- 사용자 지정 크기 및 길이로 이미지에서 비디오 클립 생성
- **스마트 워터마크**: 위치, 크기, 회전, 투명도 조절
- **시간 제어**: 특정 구간에만 워터마크 표시 또는 전체 영상에 표시
- **향상된 텍스트 및 자막**:
- 광범위한 스타일링(글꼴, 크기, 색상, 윤곽선, 배경 상자)으로 텍스트 오버레이 추가
- **스마트 위치 지정**: 정렬 프리셋(좌/중앙/우, 상/중간/하) 또는 사용자 지정 좌표 사용
- **패딩 조절**: 가장자리에서 가로 및 세로 패딩 개별 조절
- 동일한 텍스트 스타일링 옵션으로 외부 자막 파일(`.srt`) 추가 및 스타일링
- **글꼴 관리**: 텍스트 작업에 사용할 사용자 지정 글꼴(TTF, OTF) 업로드, 목록 조회, 미리보기, 검증 및 삭제.
## n8n에 설치하기
1. **설정 > 커뮤니티 노드**로 이동합니다.
2. **설치**를 클릭합니다.
3. **npm 패키지 이름 입력** 필드에 `n8n-nodes-mediafx`를 입력합니다.
4. **설치**를 다시 클릭합니다.
노드가 설치되고 n8n이 다시 시작됩니다. 그러면 노드 패널에서 "MediaFX" 노드를 찾을 수 있습니다.
구버전 n8n 또는 수동 설치의 경우:
1. n8n 사용자 데이터 폴더(기본값: `~/.n8n/`)로 이동합니다.
2. `nodes` 디렉토리로 들어갑니다: `cd ~/.n8n/nodes`.
3. 패키지를 설치합니다: `npm install n8n-nodes-mediafx`.
4. n8n 인스턴스를 다시 시작합니다.
## 노드: MediaFX
모든 미디어 처리 작업을 위한 메인 노드입니다. `리소스` 유형을 선택한 다음 해당 리소스에 대해 수행할 `작업`을 선택합니다.
### 리소스 및 작업
#### **비디오** 리소스
- `병합`: 여러 비디오 파일을 하나로 결합합니다.
- `자르기`: 비디오를 특정 시작 및 종료 시간으로 자릅니다.
- `전환`: 자동 FFmpeg 버전 감지 및 대체 지원으로 여러 비디오 간 전환 효과를 적용합니다.
- `페이드`: 하나의 비디오에 페이드 인/아웃 효과를 적용합니다.
- `오디오 분리`: 비디오를 무음 비디오 파일과 추출된 오디오 파일로 분리하여 동시에 반환합니다.
#### **오디오** 리소스
- `추출`: 비디오 파일에서 오디오 트랙을 지정된 형식(MP3, WAV, AAC, FLAC)으로 추출합니다.
- `믹싱`: 기본 비디오의 오디오를 보조 오디오 소스와 고급 기능으로 믹싱합니다:
- **볼륨 조절**: 기본 및 보조 소스 각각에 대한 독립적인 볼륨 조정
- **전체 믹스 모드**: 전체 길이에 걸쳐 오디오 믹싱 (최단/최장/첫 번째 소스)
- **부분 믹스 모드**: 정확한 시작 시간과 지속 시간으로 특정 시간 범위에 오디오 삽입
- **오디오 반복**: 짧은 오디오를 지정된 길이에 맞게 자동 반복
- **독립적인 페이드 효과**: 전체 믹싱과 부분 믹싱 모두에서 사용자 지정 길이로 페이드 인 및 페이드 아웃 효과 적용
#### **이미지** 리소스
- `이미지를 비디오로`: 소스 이미지에서 비디오를 생성하고, 길이 및 출력 크기를 지정합니다.
- `이미지 스탬프`: 고급 워터마크 기능으로 비디오에 이미지를 오버레이합니다:
- **위치 및 크기 조절**: 정확한 픽셀 위치와 크기 설정
- **회전 및 투명도**: 각도 조절과 투명도 제어
- **시간 제어**: 특정 시간 구간에만 표시하거나 전체 영상에 표시
#### **텍스트** 리소스
- `문자열 추가`: 비디오에 텍스트 오버레이를 추가합니다.
- `자막 추가`: `.srt` 파일에서 자막을 추가합니다.
#### **글꼴** 리소스
- `목록`: 사용 가능한 모든 시스템 및 사용자 업로드 글꼴 목록을 가져옵니다.
- `업로드`: 텍스트 작업에 사용할 사용자 지정 글꼴 파일(`.ttf`, `.otf`)을 업로드합니다.
- `삭제`: 이전에 업로드한 사용자 글꼴을 제거합니다.
## 사용 예제
### Merge 노드와 함께 사용하기 (v1.4.0 신규)
n8n의 Merge 노드를 사용하여 여러 비디오 입력을 결합할 때:
1. 여러 비디오 소스를 Merge 노드에 연결
2. Merge 노드를 "Combine All" 모드로 설정
3. MediaFX 노드에서 Binary Property 이름을 `data1`, `data2` 등으로 설정 (Merge 노드 출력과 일치)
4. MediaFX가 모든 병합된 입력을 자동으로 감지하고 처리
### 이미지를 비디오로 변환
단일 이미지에서 1920x1080 해상도의 10초짜리 비디오를 만듭니다.
```json
{
"resource": "image",
"operation": "imageToVideo",
"sourceImage": {
"source": { "sourceType": "binary", "binaryProperty": "data" }
},
"duration": 10,
"videoSize": {
"width": 1920,
"height": 1080
},
"outputFormat": "mp4"
}
```
### 페이드 효과가 있는 고급 오디오 믹싱
`main_video.mp4`의 15초 지점부터 30초 동안 `new_audio.mp3`를 믹싱하고, 반복 재생과 페이드 효과를 적용합니다.
```json
{
"resource": "audio",
"operation": "mixAudio",
"mixVideoSourceType": "url",
"mixVideoSourceUrl": "/path/to/main_video.mp4",
"mixAudioSourceType": "url",
"mixAudioSourceUrl": "/path/to/new_audio.mp3",
"videoVolume": 1.0,
"audioVolume": 0.5,
"enablePartialMix": true,
"startTime": 15,
"duration": 30,
"loop": true,
"enableFadeIn": true,
"fadeInDuration": 2,
"enableFadeOut": true,
"fadeOutDuration": 3
}
```
### 스마트 위치 지정으로 텍스트 오버레이 추가
정렬 프리셋과 사용자 지정 스타일링을 사용하여 비디오에 텍스트를 추가합니다.
```json
{
"resource": "subtitle",
"operation": "addText",
"source": { "source": { "sourceType": "binary", "binaryProperty": "data" } },
"textOptions": {
"text": "안녕하세요, 커스텀 폰트!",
"fontKey": "my-custom-font",
"size": 48,
"color": "yellow",
"positionType": "alignment",
"horizontalAlign": "center",
"verticalAlign": "bottom",
"paddingX": 20,
"paddingY": 50,
"startTime": 0,
"endTime": 10
}
}
```
### 고급 워터마크 스탬프 적용
특정 시간 구간에 워터마크를 적용합니다.
```json
{
"resource": "image",
"operation": "stampImage",
"sourceVideo": {
"source": { "sourceType": "binary", "binaryProperty": "data" }
},
"stampImage": {
"source": { "sourceType": "binary", "binaryProperty": "watermark" }
},
"width": 200,
"height": -1,
"x": "(main_w-overlay_w)-20",
"y": "20",
"rotation": 15,
"opacity": 0.8,
"enableTimeControl": true,
"startTime": 5,
"endTime": 25
}
```
### 비디오에서 오디오 분리 (v1.4.1 신규)
비디오를 무음 비디오와 추출된 오디오 트랙으로 분리합니다.
```json
{
"resource": "video",
"operation": "separateAudio",
"separateSource": {
"source": { "sourceType": "binary", "binaryProperty": "data" }
},
"separateVideoFormat": "mp4",
"separateAudioFormat": "mp3",
"separateAudioCodec": "copy",
"separateAudioBitrate": "192k",
"separateVideoFieldName": "video",
"separateAudioFieldName": "audio"
}
```
**출력**: 두 개의 바이너리 속성을 가진 단일 아이템을 반환합니다:
- `video`: 무음 비디오 파일 (오디오 트랙 없음)
- `audio`: 추출된 오디오 파일
## 요구 사항
- n8n: 버전 1.0 이상 권장.
- Node.js: 버전 16 이상.
- FFmpeg: `@ffmpeg-installer/ffmpeg`를 통해 자동으로 다운로드되고 포함되며, `ffmpeg-static`이 대체 수단으로 제공됩니다. 일부 시스템에서는 수동 설치가 필요할 수 있습니다.
### FFmpeg 설치
노드는 `@ffmpeg-installer/ffmpeg` 패키지를 통해 FFmpeg를 자동으로 다운로드합니다(`ffmpeg-static`이 대체 수단). 서버에서 FFmpeg 관련 오류가 발생하는 경우 수동으로 FFmpeg를 설치해야 할 수 있습니다:
**Ubuntu/Debian:**
```bash
sudo apt update && sudo apt install ffmpeg
```
**CentOS/RHEL/Rocky Linux:**
```bash
sudo yum install epel-release && sudo yum install ffmpeg
# 또는 최신 버전의 경우:
sudo dnf install ffmpeg
```
**Alpine Linux (Docker):**
```bash
apk add ffmpeg
```
**macOS:**
```bash
brew install ffmpeg
```
## 개발
이 노드에 기여하고 싶다면:
1. 이 저장소를 복제(Clone)합니다.
2. `npm install`로 종속성을 설치합니다.
3. `npm run build`로 노드를 빌드합니다.
4. 개발 중에는 `npm run dev`를 사용하여 변경 사항을 감시하고 자동으로 다시 빌드합니다.
5. [로컬 저장소를 n8n 노드 디렉토리에 연결합니다.](https://docs.n8n.io/integrations/creating-nodes/test-node/#linking-the-node)
## 저장소
**GitHub**: [https://github.com/dandacompany/n8n-nodes-mediafx](https://github.com/dandacompany/n8n-nodes-mediafx)
## 개발자
**개발자**: Dante
**이메일**: datapod.k@gmail.com
**유튜브 채널**: [단테랩스](https://www.youtube.com/@단테랩스)
## 기여하기
기여를 환영합니다! [GitHub 저장소](https://github.com/dandacompany/n8n-nodes-mediafx)에서 이슈, 기능 요청 또는 풀 리퀘스트를 자유롭게 제출해 주세요.
## 지원
- **이슈**: [GitHub Issues](https://github.com/dandacompany/n8n-nodes-mediafx/issues)
- **토론**: [GitHub Discussions](https://github.com/dandacompany/n8n-nodes-mediafx/discussions)
- **유튜브**: [단테랩스](https://www.youtube.com/@단테랩스)에서 튜토리얼과 데모를 확인하세요
## 프로젝트 후원
이 노드가 유용하셨다면, 커피 한 잔 후원을 고려해 주세요!
[](https://buymeacoffee.com/dante.labs)
## 라이선스
MIT