나만의 미디어/문서 통합 관리 허브 'OneHub' 개발

2026. 2. 25.|유승준(관리자)

나만의 미디어/문서 통합 관리 허브, 'OneHub'

OneHub (원허브): 이 앱 하나로 모든 기능의 중심(Hub)이라는 의미입니다.

1. 프로젝트 소개

안녕하세요! 이번에 개인적으로 필요해서 만들게 된 데스크톱 애플리케이션, OneHub을 소개합니다.

OneHub은 유튜브 영상/음원 추출기능(Media Hub)과 HWP-Word 양방향 문서 변환기능(Doc Hub)을 하나의 앱에서 직관적으로 처리할 수 있도록 만든 생산성 유틸리티입니다.

2. 왜 만들게 되었나요? (제작 동기)

평소 문서 작업 중 HWP와 Word 포맷을 변환해야 할 일이나, 영상 편집 일도 하고 있는데 미디어 자료를 유튜브에서 추출해야 할 일이 종종 있었습니다. 그때마다 광고가 많은 무료 사이트를 이용하거나 복잡한 CLI 툴을 써야 하는 것이 꽤 번거로웠습니다.

"내가 자주 쓰는 기능들만 모아서 직관적이고 예쁜 데스크톱 앱으로 만들어보면 어떨까?" 하는 생각에 사이드 프로젝트로 OneHub을 시작하게 되었습니다.

3. 웹의 유연함과 데스크톱의 강력함을 하나로 (기술 스택)

원활한 데스크톱 경험과 파이썬의 강력한 라이브러리들을 활용하기 위해 아래와 같은 스택을 구성했습니다.

Frontend: React, Vite (웹 기술로 세련된 UI 시각화)
Backend: Python / FastAPI (실제 영상 추출 및 문서 포맷 변환 로직 처리)
Desktop App: Electron (프론트엔드와 파이썬 백엔드를 하나의 데스크톱 앱으로 패키징)

4. 핵심 기능 및 UI 구현: 매끄러운 화면 전환 (App.jsx)

OneHub은 중앙의 토글스위치를 통해 두 가지 허브를 자유롭게 오갈 수 있습니다.

Media Hub 🎥: 포맷(Video/Audio)과 해상도를 선택해 지정된 폴더로 즉시 미디어를 다운로드합니다.
Doc Hub 📄: 드래그 앤 드롭으로 문서를 추가하고, HWP ↔ Word 변환을 간편하게 수행합니다.
Global UI ✨: Glassmorphism(유리 질감) 스타일의 디자인과 한/영 다국어를 지원합니다.

특히 두 허브(Media/Doc)를 전환할 때, 무거운 라우팅을 타지 않고 마치 스마트폰 앱을 스와이프하는 것처럼 빠르고 부드러운 UI를 구현하고 싶었습니다. 이를 위해 React Router를 사용하는 대신 상태(useState) 기반의 조건부 클래스 렌더링을 사용했습니다.

javascript

/* src/App.jsx: 상태 기반 매끄러운 토글 UI 구현 */
import React, { useState } from 'react';
import MediaHub from './components/MediaHub';
import DocHub from './components/DocHub';

function App() {
  // 현재 활성화된 허브 상태 관리 ('media' 또는 'doc')
  const [activeMode, setActiveMode] = useState('media');
  
  // 두 기능 사이를 전환하는 토글 함수
  const toggleMode = () => {
    setActiveMode(prev => prev === 'media' ? 'doc' : 'media');
  };

  return (
    <div className="app-container">
      <div className="glass-panel main-content">
        
        {/* Media Hub 영역: activeMode 일치 시 활성화 클래스 부여 */}
        <div className={`hub-section media-hub ${activeMode === 'media' ? 'active' : ''}`}>
          <MediaHub />
        </div>

        {/* 중앙 토글 스위치 */}
        <div className="toggle-container">
          <div className={`toggle-switch ${activeMode}`} onClick={toggleMode}>
            {/* 아이콘 전환 로직 생략 */}
          </div>
        </div>

        {/* Doc Hub 영역 */}
        <div className={`hub-section doc-hub ${activeMode === 'doc' ? 'active' : ''}`}>
          <DocHub />
        </div>
        
      </div>
    </div>
  );
}
export default App;

5. 트러블슈팅: Electron과 Python 백엔드의 만남 (package.json)

이번 프로젝트에서 가장 애를 먹었던 부분이자 중요한 과제는 '어떻게 Python 코드를 Electron 윈도우용 인스톨러(.exe) 안에 하나로 묶어 배포할 것인가?' 였습니다.

사용자가 앱을 쓰기 위해 파이썬 환경을 따로 구축하게 할 수는 없었기 때문입니다. 더불어 electron-builder를 세팅하는 과정에서 winCodeSign 심볼릭 링크 에러와 파일 잠금(locking) 이슈가 발생해 빌드가 실패하는 문제도 겪었습니다.

이 문제를 해결하기 위해 다음과 같은 빌드 파이프라인 설정을 도입했습니다. React 프론트엔드와 별개로, 무거운 작업을 담당하는 파이썬 코드를 PyInstaller를 이용해 가벼운 main.exe 단일 파일로 묶었습니다. 그 후 electron-builder의 extraResources 옵션을 활용하여 이 백엔드 실행 파일을 Electron 앱 패키지 내부에 숨겨 함께 배포하도록 설정했습니다.

json

/* package.json: pyinstaller & electron-builder 설정 */
{
  "scripts": {
    // 1. 파이썬 백엔드를 PyInstaller를 이용해 단일 실행 파일로 우선 빌드
    "build:backend": "pyinstaller --noconfirm --onefile --distpath ./backend/dist backend/main.py",
    // 2. Vite 빌드 후 Electron 패키징 수행
    "build": "vite build && electron-builder"
  },
  "build": {
    "appId": "com.onehub.app",
    "productName": "OneHub",
    "directories": {
      "output": "installer"
    },
    // NSIS 설정: 윈도우 인스톨러 생성 규칙 (원클릭 설치 방지, 경로 지정 허용 등)
    "nsis": {
      "artifactName": "OneHub_Setup.exe",
      "oneClick": false,          
      "allowToChangeInstallationDirectory": true,
      "createDesktopShortcut": true
    },
    // ★ 핵심 포인트: 빌드된 파이썬 실행 파일을 배포 패키지 내부(resources)에 포함
    "extraResources": [
      {
        "from": "backend/dist/main.exe",
        "to": "backend/main.exe",
        "filter": [ "**/*" ]
      }
    ]
  }
}

6. 마무리

단순한 일상의 불편함에서 출발한 아이디어였지만, Frontend(React)와 Backend(Python)를 결합하고 이를 다시 Desktop App(Electron)으로 패키징하는 클라이언트 앱 배포의 전체 사이클을 경험해 볼 수 있어 무척 뜻 깊은 프로젝트였습니다.

다음 버전에서는 제가 영상 편집을 하면서 더 필요한 기능이 생기면 업데이트를 할 예정입니다!! 해당 앱은 저의 구글 드라이브에서 다운로드 받을 수 있습니다. 긴 글 읽어주셔서 감사합니다!

26년 2월 28일 - 중단 버튼 추가, 기본 저장 경로 다운로드 파일로 지정

26년 3월 19일 :

Doc Hub - 문서 변환 엔진 개선

문제

- HWP / Word 양방향 변환 시 매개 변수의 개수가 잘못되었습니다 오류가 발생하는 문제

수정 내용

- 한글 COM API(hwp.Open) 호출 방식을 변경하여 다양한 한글 버전과의 호환성을 확보했습니다.

- Word → HWP 변환 시 업로드된 파일의 무결성 검증 및 변환 후 내용 확인 로직을 추가했습니다.

- 변환 실패 시 원인을 특정할 수 있도록 상세한 에러 메시지를 제공합니다.

빌드 및 배포 개선

- Vite 빌드 출력 경로를 dist → renderer로 변경하여 electron-builder와의 충돌을 해결했습니다.

- 프론트엔드 리소스를 extraResources로 패키징하여 설치 후 흰 화면이 나오던 문제를 수정했습니다.

- PyInstaller에서 미사용 모듈(tkinter, unittest, matplotlib, numpy 등)을 제외하고, 백엔드 콘솔 창을 숨김 처리했습니다.

- 인스톨러에 포함되는 불필요한 파일(.cjs 중복, node_modules, 소스 코드 등)을 제거했습니다.

기타

- 앱 시작 시 xml.etree 모듈 누락으로 백엔드가 실행되지 않던 문제를 수정했습니다.

26년 3월 21일 :

Mac 환경에서도 저장할 수 있게 확장

7. 다운로드

Mac Download : https://drive.google.com/file/d/1axo1zzAV03mzZVoAkEDk_XdR9yGsfGJY/view?usp=drive_link

Windows Downloade : https://drive.google.com/file/d/1qXatiY8H82LzPlAOCu04dyan1Zf69gKZ/view?usp=drive_link