Filee 딥다이브
— 파일을 바꾸는 작은 도넛 뒤의 변환 공장

1프로젝트 한줄 요약

Filee는 내 컴퓨터에서 여러 변환 엔진을 조합해 파일 형식을 바꾸는 무료 오픈소스 데스크탑 앱입니다. Windows에서는 기본적으로 Ctrl, macOS에서는 Option을 누른 채 파일을 끌면 커서 옆에 원형 메뉴가 나타납니다. 메뉴의 한 조각에 파일을 놓으면 그 조각에 연결된 프리셋으로 변환합니다. 홈 화면의 드롭 영역과 CLI도 제공합니다.

이 저장소에서 배울 핵심은 변환 알고리즘 하나보다, 서로 다른 변환기를 같은 규칙으로 연결하고 실행하는 설계입니다.

1-1. 사용자의 동작을 코드의 단위로 바꾸기

README는 이미지, PDF, Office 문서, HWP/HWPX, 미디어, 전자책, 압축 파일 등을 포함한 255가지 형식을 소개합니다. 커밋 3823747의 FormatRegistry.Known에는 262개 ID가 있습니다. 실제 파일 형식 261개와 폴더 출력용 가상 ID 1개를 합친 수이며, 모든 형식 사이의 변환이 가능하다는 뜻은 아닙니다.

1-2. 같은 기능을 명령으로 표현하면

src/Filee.Cli/Help.cs에서 확인할 수 있는 사용 문법입니다. 아래는 설치된 CLI를 사용할 때의 예시입니다.

# JPG에서 가능한 출력 형식 살펴보기
filee formats jpg

# 이미지 한 장을 품질 80의 WebP로 변환하여 converted 폴더에 저장
filee convert photo.jpg --to webp --quality 80 -o converted

화면에서 클릭하던 목표 형식과 품질을 인자로 전달했을 뿐입니다. CliHost.Create()가 같은 엔진 목록과 작업 큐를 구성하므로 핵심 로직을 다시 만들지 않습니다.

이 글의 경로는 모두 저장소 루트 기준입니다. 제품 코드는 src/ 아래에 있으므로 경로는 src/Filee.Core/Conversion/RoutePlanner.cs처럼 표시합니다. 테스트 코드는 tests/ 아래에 있습니다.

2왜 주목받는가

2-1. 짧은 기간에 관심을 모은 배경

선정 근거는 TrendShift Daily #25(2026-10-23)입니다. 2026-10-23 GitHub 기준 저장소는 2026-09-29 생성되어, 2026-10-23 기준 스타 10,465개와 포크 683개를 기록했습니다. 2026-10-21에는 v2.0.0이 출시되었습니다. 다만 이 숫자만으로 실제 사용자 수나 인기의 원인을 증명할 수는 없습니다.

제품과 코드를 보고 추론할 수 있는 매력은 분명합니다. 파일 변환은 반복해서 겪는 문제이고, 도넛 메뉴는 결과를 짧은 시연으로 전달하기 좋습니다. 국내 사용자에게는 HWP/HWPX가, 개발자에게는 CLI와 감시 폴더가 진입점이 됩니다. 다음 비교는 그런 사용 방식의 차이를 설명합니다.

Filee의 강점은 지원 형식의 숫자와 함께, 여러 전문 도구를 하나의 짧은 작업 흐름으로 묶었다는 데 있습니다.

2-2. 소스를 읽으면 홍보 문구의 경계가 보입니다

마지막 항목은 docs/ADDING-A-CONVERTER.md의 설명과 src/Filee.Engines/Infrastructure/EngineEnvironment.cs, src/Filee.Engines/Office/LibreOfficeConverter.cs의 구현이 다른 사례입니다. src/Filee.Engines/EngineRegistry.cs에도 시스템 소프트웨어를 쓰지 않는다는 오래된 주석이 남아 있습니다.

2-3. v2.0.0의 변화도 설계 학습 소재입니다

CHANGELOG.md의 2.0.0 항목은 전용 Windows 설치 프로그램, 브라우저의 이미지·파일 링크 드래그, 도넛 뒷면, 새 자르기 UI 등을 설명합니다. 현재 코드에는 이를 위한 src/Filee.Setup/, src/Filee.Core/Web/, DonutMenu.Flip.cs, CropCanvas.cs가 있습니다. 단, 현재 HEAD에는 릴리스 이후 수정도 포함될 수 있어 모든 코드를 v2.0.0 배포물과 동일시하면 안 됩니다.

3기술 스택 전체 지도

이 저장소의 중심은 .NET 10과 Avalonia입니다. 웹 앱처럼 프론트엔드와 서버 API가 따로 있는 구조가 아닙니다. 여기서 백엔드에 해당하는 것은 같은 컴퓨터의 Filee.Core와 Filee.Engines입니다. 데이터베이스 서버나 Supabase는 이 변환 흐름에 필요하지 않습니다.

3-1. 언어와 공통 빌드 설정

3-2. 프론트엔드: Avalonia 화면과 C# 상태

화면은 .axaml, 상태와 동작은 C#로 작성합니다. 예를 들어 src/Filee.App/Views/MainWindow.axaml이 MainWindowViewModel의 값을 바인딩합니다. 앱 프로젝트에는 AvaloniaUseCompiledBindingsByDefault=true가 설정되어 있습니다.

3-3. 백엔드에 해당하는 변환 계층

다음 버전은 모두 Directory.Packages.props에 선언된 패키지 버전입니다.

의존성 버전은 숫자를 외우는 대상이 아니라, 여러 라이브러리가 함께 돌아갈 수 있는 조건을 기록한 설계 자료입니다.

실제로 패키지 파일의 주석은 PDFtoImage 5.3 이상과 Svg.Skia 5.2 이상이 SkiaSharp 4를 요구하여 Avalonia 12.1 계열과 충돌한다고 설명합니다. 그래서 각각 5.2.1과 5.1.1을 선택했습니다. 이 설명은 저장소의 선택 근거이며, 모든 미래 버전에 대한 일반적인 호환성 판단은 아닙니다.

3-4. 별도 실행 파일로 사용하는 엔진

다음은 src/Filee.Engines/Infrastructure/engines.json의 기본 Windows 구성입니다. 플랫폼별 항목은 별도입니다. 버전뿐 아니라 다운로드 주소·SHA-256·크기도 함께 고정합니다.

3-5. 인프라·빌드·테스트

.github/workflows/ci.yml은 복원, 포맷 확인, Release 빌드, UI 테스트와 나머지 테스트, 설치기 검사를 정의합니다. portable.yml은 Linux x64·ARM64, macOS Intel·Apple Silicon을 다룹니다. 이 설정은 CI의 검사 절차를 정의하며, 개별 실행의 성공 여부는 해당 실행 기록으로 판단해야 합니다.

저장소에는 package.json, Cargo.toml, pyproject.toml, go.mod, Dockerfile이 없습니다. Rust는 Linux용 rhwp를 별도로 빌드할 때 등장하며, 앱의 주 구현 언어는 C#입니다. Python과 PowerShell은 주로 빌드·검증을 돕습니다.

4아키텍처 심화 분석

그림은 책임을 보여 주는 요약입니다. CLI는 ConversionService를 거치지 않고 CliHost.Create()에서 Core와 Engines를 조립합니다. 앱에서는 src/Filee.App/Services/AppHost.cs의 Build()가 이를 의존성 주입 컨테이너에 등록합니다.

4-1. 패턴 ① 인터페이스를 통한 전략 교체와 어댑터

src/Filee.Core/Conversion/IConverter.cs는 엔진이 공통으로 지킬 계약입니다. 엔진마다 API와 실행 방식이 달라도 큐는 아래 속성과 메서드만 알면 됩니다. 다음은 실제 계약에서 핵심 멤버를 추린 코드입니다.

public interface IConverter
{
    string Id { get; }
    string DisplayName { get; }
    IReadOnlyList<ConversionEdge> Edges { get; }
    int MaxParallelism { get; }
    EngineStatus GetStatus();
    Task<IReadOnlyList<string>> ConvertAsync(
        ConversionStep step, IProgress<double>? progress,
        CancellationToken cancellationToken);
}

EngineRegistry.CreateAll()에는 29개 변환기 생성식이 있습니다. 29개가 전부 외부 실행 파일인 것은 아닙니다. MagickImageConverter는 라이브러리를 감싸고, RhwpConverter는 별도 명령을 실행하며, DocxWriterConverter는 자체 작성기를 연결합니다.

학습할 때는 IConverter → EngineRegistry.CreateAll() → MagickImageConverter.ConvertAsync() 순으로 읽어 보세요. 인터페이스 선언과 실제 구현을 오가면 “추상화”의 의미가 구체적으로 보입니다.

4-2. 패턴 ② 가중 그래프를 이용한 변환 경로 계획

ConversionEdge는 한 엔진이 직접 수행하는 From → To와 비용을 나타냅니다. RoutePlanner.Plan()은 PriorityQueue<string, int>를 사용한 다익스트라 방식의 탐색을 수행합니다. MaxSteps=3이며 기본 간선 비용은 10입니다.

// 실제 RhwpConverter의 간선 중 일부
new("hwp", "pdf", Unshaped: true),
new("hwpx", "pdf", Unshaped: true),
new("hwp", "hwpx"),
new("hwpx", "hwp"),

// RoutePlannerTests.Two_step_route_is_found()의 핵심
var rhwp = new FakeConverter("rhwp", new ConversionEdge("hwpx", "pdf"));
var pdfium = new FakeConverter("pdfium", new ConversionEdge("pdf", "png"));
var route = new RoutePlanner([rhwp, pdfium]).Plan("hwpx", "png");

ConverterCatalog.CreatePlanner()는 현재 사용 가능한 엔진만 넣습니다. 사용자 우선순위에 따른 추가 비용은 Math.Min(PriorityIndex(c), 9)입니다. 이 비용은 실측 시간이나 화질 점수가 아니라, 엔진 선호와 변환 특성을 표현하기 위한 상대값입니다.

형식만 연결하면 끝나는 것이 아니라, 그 경로가 사용자의 의도를 보존하는지도 함께 검사해야 합니다.

JobQueue.RunFileAsync()는 문자의 특성을 검사한 뒤 필요하면 shaping: true로 경로를 다시 찾습니다. 다만 RhwpConverter.ScanScripts() 주석은 바이너리 HWP를 이 방식으로 검사하지 않는다고 밝힙니다. 경로 제약이 존재한다고 모든 문서의 품질이 보장되는 것은 아닙니다.

4-3. 패턴 ③ 생산자·소비자 큐와 엔진별 동시성 제한

JobQueue.Enqueue()는 Channel.CreateUnbounded<ConversionJob>()에 작업을 넣고 즉시 반환합니다. WorkLoopAsync()는 채널에서 작업을 하나씩 꺼내 실행합니다. 일반 배치에서는 작업 안의 파일들을 CPU 논리 프로세서 수 범위에서 병렬로 처리합니다.

// JobQueue.GateFor()의 실제 제한 계산
var max = converter.MaxParallelism <= 0
    ? Environment.ProcessorCount : converter.MaxParallelism;
return new SemaphoreSlim(max, max);

// RunFileAsync()의 호출 구조를 축약
await gate.WaitAsync(ct);
try
{
    outputs.AddRange(await step.Converter.ConvertAsync(stepInfo, progress, ct));
}
finally
{
    gate.Release();
}

MagickImageConverter.MaxParallelism은 0이므로 CPU 수를 따르고, rhwp는 2, LibreOffice의 Workers도 2입니다. 파일을 많이 받는 것과 특정 엔진을 무제한으로 실행하는 것은 다른 문제입니다.

이 채널은 크기 제한이 없으므로 요청 수에 대한 역압력을 제공하지 않습니다. 또한 세마포어는 JobQueue 인스턴스 안에 있으므로, GUI와 별도로 실행한 CLI까지 묶는 전역 제한은 아닙니다. 코드를 읽을 때 “어느 범위에서 제한되는가”까지 확인해야 합니다.

4-4. 패턴 ④ MVVM과 운영체제 경계 분리

Filee.Core.csproj는 Avalonia를 참조하지 않습니다. 운영체제 기능은 Core의 IPlatformServices 계약과 Windows·Linux·MacOS 구현으로 나눕니다. AppHost.Build()가 실행 OS에 맞는 구현을 선택합니다.

화면 쪽의 JobViewModel은 ObservableObject를 상속하며 [ObservableProperty], [RelayCommand]를 사용합니다. 작업 큐의 이벤트는 백그라운드에서 발생하므로 ConversionService.OnJobUpdated()가 Dispatcher.UIThread.Post()로 화면 갱신을 넘깁니다.

4-5. 한 파일의 수명과 실패 처리까지 따라가기

1. FormatRegistry.Detect()가 확장자로 형식을 찾습니다. 전체 파일 내용을 검사하는 함수는 아닙니다.
2. JobQueue.RunFileAsync()가 경로를 고르고, 중간 결과를 작업별 임시 폴더에 둡니다.
3. 마지막 출력은 할당기를 거쳐 OutputPathResolver.Resolve()의 규칙으로 이름을 정합니다.
4. 원본과 같은 경로는 덮어쓰지 않고, 기본 충돌 처리에서는 photo (2).png처럼 번호를 붙입니다.
5. 일부 파일만 성공하면 CompletedWithErrors로 구분하고, 작업 종료 때 임시 파일 정리를 시도합니다.

외부 명령에는 ProcessRunner.RunAsync()가 UseShellExecute=false와 ArgumentList.Add()를 사용합니다. 취소·시간 초과 때 프로세스 트리 종료를 시도하고 표준 출력·오류를 수집합니다. FFmpeg에는 별도의 FfmpegRunner도 있습니다. 이는 셸 인용과 프로세스 관리의 문제를 줄이는 설계이지, 변환 엔진을 운영체제 수준의 샌드박스에 넣는 기능은 아닙니다.

2026-10-27 개정: 2.1 계열의 새 변환 경로

공통 버전 설정 Directory.Build.props는 2.1.0입니다. 당시 고정 소스는 2d562869aee7402a2c3521ecebdb26e042f60364이며, 이 페이지의 기존 코드 규모·형식 개수는 2026-10-23의 관측값으로 남깁니다. 다음 내용은 새로 읽은 코드 경로이며 바이너리 실행 결과는 아닙니다.

OCR의 실행 자원과 엔진 준비

TesseractConverter는 파일 하나를 처리하면서 페이지 인식을 CPU 수에 따라 1~4개로 제한하고, 각 Tesseract의 내부 스레드는 하나로 둡니다. 언어 데이터를 작업 폴더에 복사하며 첫 사용 시 다운로드가 필요합니다. Windows는 선택 엔진, Linux·macOS는 시스템 설치본도 찾습니다. macOS의 Apple Vision 경로도 있지만 언어별 가용 조건이 다릅니다.

실습 과제: RoutePlanner.Plan(..., ocr: true)와 일반 호출을 비교해 OCR 간선이 언제 후보가 되는지 그려 보세요. 다음에는 선이 있는 PDF·선 없는 PDF·스캔에 대해 표 변환의 예상 성공/거부를 적습니다. 다운로드 완료와 인식 품질은 별도 검증 항목입니다.

2026-10-28 개정: 2.2.0의 이미지 작업과 엔진 대기

현재 Directory.Build.props의 버전은 2.2.0이며 분석 SHA는 206df593ca0bc5f00f47c3b2bdf8f6aa98e50b1f입니다. README는 현재 270개 형식을 안내합니다. 아래의 초판 규모표는 당시 관측값이며 현재 지원 수와 구분합니다.

• 이미지 편집 창: ImageEditTool.ConversionOf는 사용자의 크기·회전·품질 선택을 일반 변환 프리셋으로 바꿔 기존 작업 큐·취소·이력 경로를 공유합니다. 원본 형식으로 쓰기 경로가 없으면 PNG로 돌리는 분기도 있습니다.
• 모자이크·흐림: HideService는 EXIF 방향을 적용한 미리보기를 만들고 긴 변을 최대 2560px로 줄입니다. 애니메이션·다중 페이지 이미지는 첫 장에만 가려지는 오류를 막기 위해 거부합니다. 이름·얼굴을 가렸더라도 공유 전 최종 저장 파일에서 가린 범위를 확인해야 합니다.
• 여러 이미지 합치기: 변경기록은 위아래·좌우 배치와 자르기 비율 유지, 결과 크기 제한을 추가했다고 설명합니다. 형식별로 가능한 경로가 다르므로 등록된 형식 전체에서 같은 편집 기능이 가능하다는 뜻은 아닙니다.
• 고정 총시간에서 무응답 시간으로: StallWatch는 출력 한 줄을 진행 신호로 갱신하고 일정 시간 침묵한 프로세스를 정지로 판정합니다. 작업이 진행되는 큰 파일을 단지 총시간이 길다는 이유로 끊지 않도록 한 설계입니다.
• Windows 엔진 설치: RealPath.Of는 junction·심볼릭 링크·마운트 지점을 따라 실제 경로를 얻어 Windows Installer에 전달합니다. 사용자 AppData 경로를 옮긴 환경의 설치 오류에 대응합니다.

실습은 복사한 사진 하나로 편집 → 저장 → 원본과 크기·방향·가림 영역 비교 순서로 시작합니다. 이번 분석은 소스와 변경기록을 읽었으며 다운로드 바이너리나 외부 엔진을 실행하지 않았습니다.

근거: 2.2.0 변경기록 · 가림 미리보기 · 대기 판정

2026-10-29 소스 개정 — 자유 크기와 측정 데이터

이미지 편집 창에 자유 너비×높이 모드가 추가됐다. ImageEditTool.ResizeModes에 Custom이 들어가고, ViewModel은 픽셀·cm·mm·inch와 DPI를 다룬다. 단위를 바꿀 때 실제 픽셀 크기는 유지하며 처음 선택할 때 비율 잠금을 기본으로 둔다. 실제 프리셋은 Resize=None과 CustomSize로 저장해 기존 표현과 호환시킨다. 물리 단위를 고르면 이미지 DPI에도 반영한다.

FreeMasterText.Read()와 데이터 변환기에 FreeMASTER 오실로스코프 TXT→CSV 경로가 추가됐다. 모든 TXT가 표로 변환되는 기능이 아니다. 첫 행 # Oscilloscope Data, 탭 구분 헤더의 첫 열 # Seconds, 두 열 이상과 최소 한 데이터 행을 요구한다. 데이터 열 수가 헤더와 다르면 거부하고 출력에서는 첫 열을 Seconds로 바꾼다.

# 입력 형식 예시 (열 사이는 탭)
# Oscilloscope Data
# Seconds	Signal
0.0	12.5

Windows의 LibreOffice 탐색은 PATH·통상 폴더 외에 사용자·시스템의 32/64비트 레지스트리 설치 경로도 확인한다. 다른 드라이브에 설치한 LibreOffice를 발견하기 위한 변경이며 엔진을 자동 설치했다는 뜻은 아니다. 앱·설치 프로그램 공유 언어 목록에는 이탈리아어가 추가됐다. 위 기능은 소스 분기로 확인했고 실제 변환·편집을 실행하지 않았다.

형식 목록을 자동화에 넘기는 JSON 계약

현재 CLI의 filee formats --json은 formats 배열을, filee formats pdf --json처럼 형식을 지정한 호출은 해당 형식의 정보와 targets·withEngines 배열을 반환합니다. 각 형식 정보는 id·name·category·extensions·writable을 담습니다. targets는 지금 설치된 엔진으로 가능한 변환, withEngines는 추가 엔진이 있을 때 가능한 변환이므로 둘을 합쳐 현재 즉시 지원한다고 표시하지 않습니다.

# 독자의 별도 설치 환경에서 선택할 예시
filee formats --json
filee formats pdf --json

README는 270개 형식을 안내합니다. 새 입력인 Bink(.bik)는 FFmpeg의 demuxer·decoder로 읽을 뿐 Bink 인코더가 없어 .bik 출력을 만들지 않습니다. Apple Voice Memos .qta 역시 읽기 전용이며, FFmpeg가 해독할 수 있는 첫 오디오 트랙을 변환합니다. iOS 26의 공간 APAC 트랙은 decoder가 없다는 제한이 있습니다. 형식 등록 수와 읽기·쓰기 가능 범위는 별개입니다.

2026-10-30 후속 대조: Windows ARM64와 설치 대기

고정 커밋 7fc129f는 앱·CLI·Setup·Explorer 메뉴 DLL과 번들 엔진의 Windows ARM64 패키징 경로를 추가합니다. 추가 다운로드 엔진까지 전부 ARM64라는 뜻은 아닙니다. EngineDownloads.DownloadRuntime는 win-arm64에서 Windows build 22000 이상일 때 win-x64 목록을 선택해 에뮬레이션을 사용합니다. Windows 10 ARM에는 그 x64 다운로드를 제공하지 않습니다. 배포 자산의 실제 제공 여부는 릴리스에서 확인해야 합니다.

엔진 페이지는 하나를 설치하는 동안 다른 행의 설치 요청도 대기열에 넣을 수 있습니다. UI 명령은 동시 요청을 받지만 서비스의 semaphore가 실제 설치를 한 번에 하나로 제한하므로 병렬 설치로 설명하지 않습니다. CLI 도움말에는 filee presets --json이 추가되었고 종료 코드 0은 건너뛴 파일을 포함해 “실패 없음”을 뜻합니다. 코드 1은 일부 실패 또는 취소를 포함하므로 종료 코드만으로 모든 파일이 변환되었다고 판정하면 안 됩니다.

5디렉토리 구조 해부

5-1. 가장 큰 폴더가 알려 주는 것

엔진 폴더가 가장 큽니다. Filee는 외부 프로그램만 호출하는 얇은 껍데기가 아닙니다. 예를 들어 src/Filee.Engines/Hwp/Hwpx/에는 문서 모델과 읽기·쓰기 코드가 있고, src/Filee.Engines/Office/에는 내장 DOCX 작성기를 연결하는 변환기가 있습니다.

5-2. 코드 규모 집계 기준

집계 대상은 git ls-files에 나오는 추적 파일 852개 중 확장자별 파일이며, 물리 줄 수는 Python의 read_bytes().splitlines() 길이를 합산한 값입니다. 빈 줄·주석을 포함하고, 미추적 빌드 결과나 외부 엔진의 소스는 포함하지 않습니다. 코드의 논리 줄 수와는 다릅니다.

테스트 C# 줄 수는 제품 C# 줄 수의 약 52.2%입니다. 이것은 테스트 코드의 양을 보여 주며 커버리지 52.2%라는 뜻은 아닙니다. 파일 규모만으로 전체 커밋 수·기여자 수·개발 속도를 판단할 수도 없습니다.

5-3. 초보자를 위한 읽기 순서

1. FileFormat.cs와 FormatRegistry.cs: 입력과 형식을 먼저 이해합니다.
2. IConverter.cs와 RoutePlannerTests.cs: 작은 계약과 예제로 이동합니다.
3. RoutePlanner.cs와 JobQueue.cs: 계획과 실행을 분리해 읽습니다.
4. ConversionService.cs와 JobViewModel.cs: 결과가 화면에 도착하는 길을 봅니다.
5. 관심 있는 엔진 하나를 고릅니다. 첫날부터 모든 파일 포맷의 내부 구조를 읽을 필요는 없습니다.

6학습 포인트 (기술별)

6-1. C#: 계약과 데이터 모델을 읽는 법

ConversionEdge는 readonly record struct, ConversionStep은 sealed record입니다. 작은 값과 한 단계의 실행 문맥을 구분하고, 이름 있는 인자로 선택 조건을 전달합니다. CancellationToken과 IProgress<double>도 계약의 일부입니다.

실습 아이디어: ConversionEdge의 필드마다 “이 조건이 없으면 생기는 잘못된 변환”을 한 문장씩 적어 보세요. 문법을 아는 데서 끝내지 않고 타입이 어떤 사고를 막는지 설명하는 연습입니다.

6-2. 그래프: 비용과 제약을 분리하기

RoutePlanner의 dist는 현재 비용, prev는 직전 단계, hops는 단계 수를 저장합니다. 출발점과 목표가 같을 때도 재인코딩하려면 자기 자신으로 향하는 간선이 필요합니다. 단순히 “형식이 같으니 끝”이라고 처리하지 않습니다.

실습 아이디어: 가짜 엔진의 A → B 비용을 8, B → C를 8, A → C를 25로 두고 경로를 손으로 계산합니다. 여기에 B → C의 DirectOnly를 켜면 왜 결과가 달라지는지 RoutePlannerTests와 대조해 보세요.

6-3. 비동기: 응답성과 처리량은 별개의 문제

큐는 UI 호출을 빨리 반환하게 하고, 파일 병렬화는 처리량을 높입니다. 세마포어는 엔진을 동시에 호출하는 수를 제한합니다. async가 자동으로 CPU 작업을 여러 코어에 나누거나 네이티브 엔진을 안전하게 만들지는 않습니다.

실습 아이디어: 10개 파일, CPU 논리 프로세서 8개, rhwp 제한 2개라는 가정으로 “대기 중인 파일”과 “엔진에 들어간 파일”을 나누어 그려 보세요. 다음에는 취소 요청 시 finally가 왜 필요한지 설명합니다.

6-4. 문서 처리: 중간 모델로 조합 폭발 줄이기

src/Filee.Engines/Hwp/Hwpx/HwpxModel.cs의 HDocument를 여러 읽기·쓰기 경로가 공유합니다. DocumentReaders.ReadAsync()가 입력을 모델로 바꾸고, DocxWriterConverter.ConvertAsync()가 그 모델을 DOCX로 씁니다.

DocxWriterConverter의 기본 간선 비용은 8이고, PDF 입력에는 DocumentReaders.PdfPenalty=6을 더합니다. 읽기와 쓰기를 나누면 새 입력을 추가할 때 여러 출력으로 연결할 수 있지만, 중간 모델에 표현되지 않는 원본 기능은 잃을 수 있습니다.

중간 모델은 변환 조합을 늘려 주지만, 모델에 담지 못한 정보까지 보존해 주지는 않습니다.

실습 아이디어: 제목·문단·표·수식·그림이 있는 문서의 각 요소가 모델에서 무엇으로 표현되는지 표를 만드세요. “결과 파일이 열림”과 “의미가 보존됨”을 다른 검증으로 다룹니다.

6-5. Avalonia와 수학: 그리기와 판단을 떼어 내기

src/Filee.App/Controls/DonutGeometry.cs의 Span(), AngleOf(), IndexAt(), HitTest()는 각도·거리로 메뉴 조각을 고릅니다. 도넛을 그리는 코드와 이 계산을 나누어서 경계값을 테스트할 수 있습니다.

실습 아이디어: 네 조각 도넛의 위·오른쪽·아래·왼쪽 점을 종이에 찍고 IndexAt()의 결과를 계산합니다. 12시 방향을 기준으로 시계 방향 각도를 쓰는 이유도 찾아보세요. 대응 테스트는 tests/Filee.App.Tests/DonutGeometryTests.cs입니다.

6-6. 신뢰 경계: 다운로드한 바이트와 실행할 도구

EngineInstaller는 내려받은 엔진을 SHA-256과 대조한 후 풀고, 준비용 폴더에서 설치를 진행합니다. 일반 웹 파일을 받는 WebDownloader는 쿠키·자격 증명을 보내지 않으며 2 GiB 상한, 리다이렉트 5회, 응답·정체 30초 제한을 둡니다.

실습 아이디어: 엔진 다운로드와 웹 원본 다운로드의 신뢰 근거를 비교하세요. 전자는 저장소가 고정한 해시가 있고, 후자는 원격 사이트의 파일입니다. 일반 파일 다운로드의 HTTPS 하향 이동 금지 규칙을 엔진 설치기에 그대로 있다고 가정하면 안 됩니다. 설치기는 고정 해시 검증을 전제로 일부 HTTP 미러 이동을 허용합니다.

7하드웨어 / 시스템 요구사항

근거는 README.ko.md, installer/linux/INSTALL.txt, installer/macos/INSTALL.txt, build/build-portable.ps1입니다. macOS 패키지는 아직 공증 전이라는 안내가 있으며, calibre 다운로드의 minimumMacOS는 14.0입니다. 앱의 최소 OS와 엔진의 최소 OS가 다를 수 있습니다.

7-1. 메모리와 디스크는 입력 규모에 따라 달라집니다

README와 설치 안내에는 공식적인 최소 RAM·CPU 코어 수·GPU 사양이 없습니다. 학습용으로는 메모리 8GB 이상과 디스크 여유 공간 수 GB를 초기 예산으로 제안하지만, 이는 학습용 자원 예산 예시이며 벤치마크나 작동 보증이 아닙니다. 첫 예제는 작은 이미지나 짧은 문서로 잡으세요.

예를 들어 6,000 × 4,000 픽셀의 8비트 RGBA 버퍼 하나만 약 96MB, 즉 약 91.6MiB입니다. 여기에 원본·복사본·프레임·병렬 작업이 더해집니다. 이는 일반적인 버퍼 계산이며 Filee의 실제 사용량을 측정한 값이 아닙니다.

설치 파일의 크기보다 입력을 펼친 뒤의 크기와 동시에 처리하는 파일 수가 실행 자원을 더 크게 좌우합니다.

7-2. 오프라인으로 쓰려면 무엇을 미리 준비할까?

로컬 변환 경로에 필요한 엔진과 글꼴이 준비되어 있어야 합니다. src/Filee.Engines/Infrastructure/engines.json의 기본 Windows 구성에서 FFmpeg 다운로드는 99,899,672바이트, LibreOffice는 373,252,096바이트입니다. 이 값은 파일에 적힌 다운로드 크기이지 전체 설치 용량이 아닙니다.

네트워크가 없는 상태에서는 새 엔진과 웹 원본을 받을 수 없습니다. UpdateService에는 6시간 간격의 업데이트 확인 설정도 있습니다. 따라서 “오프라인 변환 가능”을 “앱에 네트워크 기능 자체가 없음”으로 해석하지 마세요.

8직접 해볼 수 있는 실습 과제

배포 검사의 범위를 읽는 과제로 build/smoke-launch-app.py를 살펴볼 수 있습니다. 이 도구는 패키지 앱의 시작·종료, macOS의 두 번째 실행 전달, Linux X11 입력 훅 오류를 확인합니다. 변환 결과나 이미지 편집 정확도를 검사하는 테스트는 아니므로 별도의 샘플 파일 검증이 필요합니다. 이 검토에서는 해당 도구를 실행하지 않았습니다.

아래는 독자를 위한 제안입니다. 구현 과제는 별도의 학습용 사본에서 수행하는 것을 전제로 합니다. 각 과제는 입력·예상 출력·근거를 설명할 수 있는 결과물을 목표로 삼습니다.

9관련 기술 심화 학습 로드맵

하루에 저장소 전체를 이해하려 하면 파일 형식의 세부사항에 묻히기 쉽습니다. 아래 과정은 한 주마다 읽을 파일, 설명할 개념, 남길 결과물을 정해 진도를 확인합니다. C#이 처음이라면 첫 주를 두 주로 늘리고 작은 코드 예제부터 읽어도 됩니다.

매주 한 기능을 입력부터 출력까지 설명할 수 있게 되면, 큰 저장소도 읽을 수 있는 작은 경로들의 모음이 됩니다.

9-1. 관심 분야에 따른 다음 갈림길

• 시스템 설계: 현재 무제한 채널에 크기 제한을 도입할 때 UI·대기·취소가 어떻게 달라질지 설계합니다.
• 문서 처리: OOXML·HWPX의 ZIP/XML 구조와 문서 모델 사이의 정보 손실을 추적합니다.
• 데스크탑 UI: DonutGeometry의 좌표 계산과 실제 그리기를 비교하고 입력 경계값을 정리합니다.
• 자동화: FolderWatcher.ProcessPendingAsync()에서 쓰기 중인 파일과 완성된 파일을 구분하는 규칙을 읽습니다.
• 배포: Linux용 rhwp를 Ubuntu 22.04에서 따로 빌드하는 이유를 glibc ABI와 연결해 설명합니다.

10핵심 키워드 사전

11참고 링크

2026-10-30 추가 근거 (분석 SHA aad99622f110c8b66a3ac7115e8ff6375fdc5699): README.md · Directory.Build.props · docs/ENGINES.md · src/Filee.Cli/Cli.cs · src/Filee.Cli/Help.cs · src/Filee.Core/Formats/FormatRegistry.cs. 설치·빌드·모델 호출 없이 소스를 대조했습니다.

2026-10-29 재검토: 공식 소스 커밋 11769a896a496292ab4bf899020164d767fd60f4. 아래 초판 기록과 현재 소스 개정 내용을 구분한다.

2026-10-28 재검토 소스: 206df593ca0bc5f00f47c3b2bdf8f6aa98e50b1f. 설치·외부 모델 호출·실행 없이 아래 파일을 대조했습니다.

README.ko.md · CHANGELOG.md · Directory.Build.props · src/Filee.Core/Conversion/RoutePlanner.cs · src/Filee.Core/Conversion/IConverter.cs · src/Filee.Engines/Ocr/TesseractConverter.cs · src/Filee.Engines/Pdf/PdfTablesConverter.cs · docs/GNOME-WAYLAND.md · installer/linux/kwin/filee-donut/contents/code/main.js

11-1. 프로젝트와 근거 파일

• 공식 저장소 · v2.0.0 릴리스 · TrendShift의 Filee 페이지
• 한국어 README · 변경 기록
• SDK 설정 · 공통 빌드 설정 · 패키지 버전
• 변환기 계약 · 변환기 등록
• 경로 탐색 · 작업 큐 · 형식 목록
• 출력 경로 규칙 · 감시 폴더
• 문서 입력 어댑터 · DOCX 출력 연결
• 엔진 위치 조회 · 엔진 다운로드 명세 · 프로세스 실행
• 앱 서비스 조립 · 작업과 화면 연결 · 도넛 기하 계산
• 경로 탐색 테스트 · 출력 이름 테스트 · 플랫폼별 CI
• 프로젝트 구조 문서 · 엔진 안내 · 변환기 추가 안내
• MIT 라이선스 · 서드파티 고지

11-2. 관련 기술의 공식 학습 자료

아래는 다음 학습을 위한 공식 문서 링크입니다. 본문에 인용한 버전과 Filee의 동작 근거는 최신 문서의 예제가 아니라 위 커밋의 프로젝트 파일과 소스입니다.

• C# 공식 문서 · .NET 병렬 프로그래밍
• System.Threading.Channels · MVVM Toolkit
• Avalonia 공식 문서 · NuGet 중앙 패키지 관리
• FFmpeg 공식 문서 · ImageMagick 처리 개념 · Pandoc 사용 설명서

초판 관측표 (2026-10-23, 현재 규모 수치 아님)