┌───────────────────── Windows File Explorer ───────────────────────┐
│ Right-click on file(s) │
│ ├─ Windows 11: FileeExplorerMenu.dll (C COM, IExplorerCommandHandler)
│ └─ Windows 10: Classic Registry Cascading Submenus │
└────────────────────────────────┬───────────────────────────────────┘
│ Spawns windowless with IDC_WAIT spinner
▼
┌───────────────────────────────────┐
│ filee-run.exe (4 KB native Win32) │
└────────────────┬──────────────────┘
│ Spawns headless (CREATE_NO_WINDOW)
▼
┌──────────────────────────── Filee.Cli ─────────────────────────────┐
│ Headless Command Line Runner (filee-cli.exe) │
│ ├─ Parses arguments & options (--to, --preset, --quality, @list) │
│ └─ Delivers native Action Center Toasts via ToastNotification │
└────────────────────────────────┬───────────────────────────────────┘
▼
┌──────────────────────────── Filee.Core ────────────────────────────┐
│ RoutePlanner (Dijkstra over converter edges) │
│ JobQueue · FormatRegistry · OutputPathResolver · Settings │
└────────────────────────────────┬───────────────────────────────────┘
▼
┌──────────────────────────── Filee.Engines ─────────────────────────┐
│ 9 Core High-Performance Engines: │
│ ├─ SkiaSharp: Raster Images (PNG, JPG, WEBP, BMP, GIF, ICO) │
│ ├─ Svg.Skia: Vectors (SVG, SVGZ → PDF, PNG, JPG) │
│ ├─ PDFium (PDFtoImage): PDF rasterization │
│ ├─ PdfSharp & PdfPig: PDF manipulation & text extraction │
│ ├─ DocxWriter & Markdig: Word DOCX & Markdown/Text conversion │
│ ├─ ExcelDataReader: Spreadsheets (XLSX, XLS, ODS, CSV) │
│ └─ System.Text.Json / YamlDotNet / Tomlyn: Structured Data │
└────────────────────────────────────────────────────────────────────┘
- Trigger – The user right-clicks a file in File Explorer and selects a conversion target from the cascading submenu, or invokes
filee-cli.exedirectly. - Launch & Visual Feedback – On Windows Explorer clicks,
filee-run.exeinstantly turns the cursor into theIDC_WAIThour-glass/spinner and launchesfilee-cli.execompletely hidden (without console flash). - Plan –
RoutePlanneruses Dijkstra's algorithm over registered converter edges to compute the shortest conversion graph from source to target (maximum 3 hops). - Run –
JobQueueexecutes converter steps with concurrency control. Intermediate files live in private user temporary folders (WorkFolders.Root); final outputs are placed byOutputPathResolver. - Completion & Notification – When invoked with
--notify,Filee.Clidelivers a native Windows Action Center toast upon job completion. Output files are placed alongside the source or into the requested destination. (no Recycle Bin on the drive, a file open elsewhere, a read-only file), both stay and the file's notice says why, with a translated reason (trash.*). A result "Only if smaller" copied from the source leaves the source alone. Watch folders and files from a browser never replace. "Merge into one PDF" converts each file to PDF and merges with PDFsharp. "Compress into one archive" packs the dropped files, unconverted, with the archive engine (IFileCombiner). "Merge videos", "Merge audio" and "Video from images" join the files, in the order picked in the merge order window, into one file with FFmpeg (IMediaJoiner); pictures become PNG through the image engines first. Like the other one-file jobs, the output follows "subfolder only for several files", and a join that fails or is cancelled is undone by the job's allocator, which deletes only paths that were the job's own. "Merge images" puts the pictures, in the order picked in the same window (with their layout: one under another or side by side, the same width or their own sizes, a gap and a background), into one image with SkiaSharp (IImageJoiner), in the first picture's format (PNG, JPEG, WEBP). A merged image over 32,767 px per side or exceeding memory limits is rejected safely. - Report – progress and results appear in the toast window and in Home → Recent conversions.
Renderers check only the original source for referenced fonts.
ConversionStep.MissingFontsreports any missing families toFileResult.MissingFonts; the toast card can offer one trusted source, while the CLI and watch jobs report the names without pausing conversion or installing anything.
A picture, a link to a file or a download dragged out of a browser opens the donut like a file from the file manager.
A drag gesture over a browser (WebBrowsers, by process name) counts as over the file manager, so the default scope
covers it; click and key gestures don't, as they read the file manager's selection.
DraggedFiles.Read asks BrowserDrags (App, reads Avalonia's drag data) first; BrowserDrag (Core, pure rules)
decides what in the drag is a file:
| Source | What the drag carries | What Filee takes |
|---|---|---|
| Chrome / Edge, Windows | the picture as a virtual file (FileGroupDescriptorW + FileContents, which Avalonia 12 gives as a storage item without a local path), a .url virtual file for links, UniformResourceLocatorW, text/x-moz-url, HTML Format |
the picture's own bytes; for a link, its address |
| Firefox, Windows | the picture written to %TEMP% (CF_HDROP), text/x-moz-url, file promise formats |
the temporary copy (a local file in the temp folder and a web address on the drag) |
| Chrome / Firefox, Linux | text/x-moz-url, _NETSCAPE_URL, text/html (Avalonia turns text/uri-list into local files only and drops http addresses) |
the address |
| Safari / Chrome, macOS | file promises (not receivable through Avalonia), public.url, public.html, sometimes picture data |
the address, else the picture data |
Rules, in order: files handed over with their bytes (never .url shortcuts or programs); a picture (an HTML fragment
that is one <img> and no text, or a Firefox file promise); a DownloadURL a page sets; links only when the address
ends in an extension Filee converts and isn't a web page (.html, .php, none); last, picture pixels for a blob:
picture. Plain text is never read. data: addresses are decoded.
Until the conversion runs, the files stand as placeholders (WebDrop): paths in %TEMP%\Filee\web\<drop>\drop\<n>\
(web/ in the work root on Linux and macOS) named like the file will be, so the donut picks the profile by extension without touching the network. No HEAD request
is made: a picture without an extension stands as .jpg and a link without one isn't offered. ConversionService.Start
gives the job a WebDropFetcher (ISourceFetcher): JobQueue saves every source first (half of its progress), then
converts. Failures are per file (error.web_*), cancelling stops a download, and the job toast/ring shows both phases.
While files are saved, a badge pops up above the donut's progress ring and above the toast's progress bar with the
speed and the amounts ("2.4 MB/s · 12.3 / 48.0 MB", "· 2 of 3 files" for several): FileResult.Transfer holds each
file's byte count, ConversionJob.Transfer() sums them, and DownloadBadge (App) averages the speed over the last
second with the Engines page's TransferRate and units, rewritten four times a second and shown after 300 ms.
- Where: Settings → General → "Files dragged from a browser" (
AppSettings.BrowserDrops): the user's Downloads folder (IPlatformServices.DownloadsFolder: the shell's known folder on Windows,XDG_DOWNLOAD_DIRon Linux,~/Downloadson macOS) or a chosen one. "Next to the source" means this folder for these files (OutputRule.SourceFolder, set per job, never saved), so subfolder rules apply there and fixed folders stay fixed. - Save only the converted file: the original goes to the drop's work folder, which
Releasedeletes when the job ends; leftovers from a crash are deleted at start-up after a day. - Downloads (
WebDownloader): http and https only, at most 5 redirects (never from https to http or off the web), 2 GB cap whether or not the server says the size, 30 s to answer and 30 s without data at most. No cookies or credentials are sent: a file behind a sign-in comes back as the sign-in page, which is refused as a web page ("save it from the browser first"). A browser's own bytes (virtual files, Firefox's copy) don't have that limit. Only the public internet is reached (LocalNetwork): an address on this computer or the local network (loopback, private, carrier-grade NAT, link-local, unique local, multicast,localhostand.localnames, IPv4 inside IPv6) is refused (error.web_local_address), on every redirect and after the name is looked up: the handler'sConnectCallbackconnects only to the checked addresses, so a name that changes its answer (DNS rebinding) gets nowhere. A connection to the user's proxy isn't checked; the names and numbers in the address still are. "Allow links to this computer and the local network" (Settings → General,BrowserDropSettings.AllowLocalNetwork, off by default, read for each drop) lifts this for an intranet or a NAS. Those downloads go through anHttpClientof their own, so a pooled connection to a local address never serves a drop that may not go there. - Names and safety: Content-Disposition, else the page's name, else the address; then the first bytes decide the
extension of pictures and PDFs (
.jpgthat is WebP becomes.webp). Names are cut to a plain file name (no folders, no device names, at most 120 characters) and never replace an existing file (name (2).ext). Programs, installers and scripts are refused by extension, media type and first bytes; nothing downloaded is ever run, and every file goes through the same converters as any other. - Mark of the Web (
Platform/MarkOfTheWeb, Windows): every saved file gets aZone.Identifierstream as a browser's download would (ZoneId=3, andHostUrlwith the address a download came from, without sign-in or fragment), so SmartScreen, Office's block on macros from the internet and Protected View still apply.JobQueuecopies a source's mark onto the files converted from it (also for "Save only the converted file"); a folder result is left to its engine (the archive engine marks what it unpacked). A drive without NTFS streams gets no mark, and that never fails a conversion.
Controls/DonutMenu.cs draws the ring itself (no child controls) for speed. DonutGeometry.cs holds the pure math
(slice angles, hit testing) and is unit tested. The same control is the live toolbar and, with IsEditMode, the
editor on the Donut toolbar settings page (drag to reorder, ✎ / right-click to edit).
Animations are small springs advanced per frame; Motion.Enabled == false (Reduce animations) snaps them.
Every ToolbarProfile has two faces: PresetIds (the front) and BackPresetIds (the back; the built-in donuts get
the less common formats and tools of their file type, see BuiltInData.CreateProfiles). The flip key
(DonutSettings.FlipKey, Tab unless recorded otherwise in Settings → Shortcuts; EffectiveFlipKey refuses keys the
donut or a keyboard shortcut uses) and the mouse wheel (FlipWithWheel, one flip per turn of the wheel: notches less
than DonutMenu.WheelQuietMs apart are one turn) flip the open donut (DonutMenu.Flip.cs): the ring turns about its
vertical axis in 200 ms, an open group's ring folding first, and halfway, edge-on, FaceSwapping has
RadialViewModel show the other face, so slices, hit tests and drops always belong to the face that is drawn.
Reduce animations swaps the faces at once. RadialViewModel builds both faces with the same PresetAvailability
check (the back right after the front is on screen); a face with no slice for the files (or none at all) isn't
flipped to, and only then does the hub leave out its "⟳ Tab back" hint (a mouse in place of the key when only the
wheel flips). In click mode the focused window gets the key (DonutMenu.HandleKey) and the donut the wheel. During a
drag the donut's window has no keyboard focus, so RadialController turns on TriggerService.WatchFlipKey while
the drag donut shows files and flips on FlipKeyPressed / FlipWheelTurned: the global hook only listens (it
can't hold an event back; Explorer and Finder ignore Tab during a drag) and reports one flip per key press. On
macOS the drag donut takes the keyboard once files are on it (RadialController.TakeKeyboard), and the key reaches
its window as in click mode: while another app holds Secure Input (Terminal with Secure Keyboard Entry can keep it
from the background) macOS gives no keys to a hook, only to the app in front. The hook's copy of a press is ignored
while the window has the keyboard (HookFlipsKey, one flip per press, following IsActive); the keyboard goes back
to the app that had it once a conversion starts or the donut closes (IPlatformServices.RememberFrontApp /
ReturnFocus), unless the user clicked elsewhere meanwhile, and stays with Filee when the drop opens a window of its
own (a tool, the merge order, the save dialog). Not on Windows, where taking the keyboard during a drag breaks Explorer's.
The editor's Front / Back switch (ToolbarPageViewModel.EditingBack) edits either list with the same drag and drop.
A group is one slice that opens up to six non-group actions. Its members may be conversions or interactive tools
(for example the PDF Edit group contains Crop and the page editor); groups cannot contain another group. The group
editor offers both kinds, and UserDataStore.EnsureConsistency removes missing, duplicate, nested or excess members
without excluding tools. A group slice is marked with a small chevron by its outer edge, drawn in the slice's transform
(DonutMenu.DrawGroupMark), which also marks a dragged group in the toolbar editor.
"Annotate" (tool-annotate, palette only, settings schema 60) draws pen lines, arrows, boxes, highlights, text and
numbers on pictures (ImageOptions.Annotations): points are parts of the picture, sizes parts of its shorter side.
Engines/Annotations/AnnotationPainter(SkiaSharp) draws the marks, always at the picture's own size in pixels. The window'sAnnotationCanvascalls it on Avalonia's own Skia canvas (a custom draw operation throughISkiaSharpApiLeaseFeature), scaled to where the picture is shown, andAnnotatoron layers over the part the marks cover, a band at a time, laid over the picture inImageEncoder.ApplyOptionsafter hidden areas (converted to a CMYK picture's colours; a greyscale picture becomes a colour one): the preview is the file. Text is shaped with HarfBuzz (Vector/GlyphOutlines) in the system's bold sans-serif, each run of letters it lacks in a font the system finds.AnnotationSetkeeps the marks, the selection and undo / redo (a drag is one step). A mark just drawn isn't selected: a colour picked next goes to the next mark; with Select, colour and width restyle the selected one.AnnotateTool.ConversionOf(Core) turns the tool into a conversion in the picture's own format (as Pixelate / blur), run by the job queue;ReworksPixelsincludes the marks.
"Add background" (tool-background, palette only, settings schema 64) sets pictures on a gradient, a colour or a
picture of one's own, with padding, rounded corners, a shadow and a canvas shape (BackdropOptions). Sizes are parts of
the picture (padding of its longer side, corners of its shorter side), so a look suits any picture.
BackgroundTool.ConversionOf(Core) turns the tool into a PNG conversion withImageOptions.Backdrop, run by the job queue like Pixelate / blur's areas:ReworksPixelsincludes it, so it is applied once, in the first transform step. The tool keeps the last look apart, inImageOptions.BackdropLook; an export or import leaves out the path of a picture of one's own.Engines/Magick/BackdropComposercomposes it inImageEncoder.ApplyOptions, after resizing, background removal and grayscale and before the density, metadata and alpha steps. The picture is brought to sRGB as it is seen (through its profile, or by formula for CMYK and grey); the canvas grows round it to the shape (never crops) and stays within a pixel limit (PictureSizeOn). It is drawn by Skia as the window draws it: a linear gradient shader, a colour, or one's own picture covering (ReadPictureBehind: a raster picture of a few kinds, by extension or by its first bytes, its size checked before it is decoded, read as large as covering the canvas takes and cropped to it, in sRGB, white where see-through; one that can't be read refuses the file); the picture with its corners cut round in its own pixels; Skia's drop shadow of what shows of it, blurred at most at a sigma of 100 (a wider one drawn smaller and scaled up, where Skia's blur stays Gaussian). The canvas is drawn in tiles at most 2048 px wide, a band at a time, as RGB: a blur is never larger than a tile and the shadow's reach round it (a wider shadow is blurred once, scaled down until its sigma is 100 or less). The EXIF thumbnail is dropped.BackgroundViewModeldraws the same composition live with Avalonia: the layout and shadow from the composer's formulas (an Avalonia drop shadow is Skia's), the picture and the one behind read through the composer's functions, the preview never mirrored in a right-to-left UI. A picture behind is read when it is chosen, and again when it is picked again; Save waits for one that can be read, and one whose file changed since it was read (time written or length) is read again and shown before it is saved. The conversion carries that stamp, and the composer refuses the file (error.background_picture_changed, which the toast offers no Retry for) when the picture behind changed since, before it is read or after: a change after Save gives no file rather than one with a picture behind the window didn't show. A change that keeps both the time and the length (a copy that keeps the time, of a picture of the same size) isn't told apart, and the picture itself edited meanwhile isn't looked for (as in Pixelate / blur and Annotate). One look for all pictures or one each; failures end on a summary, as in Pixelate / blur.
The image Crop tool (tool-crop) and PDF Crop (tool-pdf-crop) open Views/CropOverlayWindow instead of running a job:
the files one after another,
each cropped by hand and saved by CropService (the preset's output rule, the source's quality kept, animated or
multi-frame pictures refused, the EXIF thumbnail dropped), one history entry for the run. A PDF preview is rendered
with PDFium and the chosen rectangle changes every page's crop box in a copied document opened in modify mode, so
text, vectors, outlines, forms, page labels and document information remain PDF objects and stay attached.
CropOverlayViewModelwalks the queue (Enter saves and opens the next file, Skip, Esc closes), keeps aCropQueueItemper file for the strip of thumbnails (waiting, current, done, skipped, failed; a thumbnail is a small copy of the preview, made once) and, after the last file, shows the summary when something failed or was skipped. Every file starts free and whole, its portrait/landscape choice following the picture.Controls/CropCanvasis the stage: the picture insideImagePadding, the part outside the frame frosted (a copy at most 40 px across, drawn large) under a veil of the page colour, the frame in the accent colour with round handles, a rule-of-thirds grid while dragging and a size chip that follows the frame. A frame being moved snaps onto the picture's vertical or horizontal centre line withinCropMath.SnapDistance(8 px) and shows that line as a dashed guide until the drag ends. The preview is downscaled once byCropService.LoadPreviewAsync; nothing is decoded again while dragging. Programmatic changes (reset, a ratio, a new picture) ease in with tweens read against the clock, so a lost frame never leaves one half done; dragging and arrow-key nudges follow at once, andPlayAnimations(fromMotion.Enabled) turns all of it off.Controls/AspectDialis a small donut of the ratios (free, original, 1:1, 5:4, 4:3, 3:2, 16:9): each slice aRingSegmentbutton that answers only inside its wedge (DonutGeometry.Wedge, rounded by the softness), the hub swaps portrait and landscape. A with the pointer over the stage opens it around the pointer, as the donut opens, growing from its middle and kept inside the window; A without a pointer there (the keyboard) and its toolbar button open it over the button with a slice focused for the arrow keys.AspectGlyphis the dial in miniature on that button, andCropSummaryRingthe end summary's donut (a slice per file).Controls/CropMathholds the arithmetic (ratios and their portrait forms, nudging by whole pixels, the frame in pixels, where the size chip goes, where the dial opens) and is unit tested.
tool-pdf-pages opens Views/PdfPageEditorWindow: it previews, reorders, rotates, deletes, adds and extracts pages.
Each source PDF's bytes and page sizes are cached once after the window has appeared; thumbnails and the large preview
render off the UI thread. A whole-document edit keeps the original catalogue and changes /Rotate in modify mode.
An actual reorder, deletion, addition or extraction builds a new PDF from selected page objects. A PDF that opens
without a password but requires an owner password for modify mode uses the same page-copy fallback as compression;
its outlines and form fields are not preserved by that fallback. Generated copies are writable even when the source
has the read-only attribute; the source's bytes and attributes are left alone.
The Cut a clip tool (tool-clip, first on the back of the video donut) opens Views/ClipWindow instead of running a
job. The window only chooses the clip; writing it is an ordinary conversion.
Core/Presets/ClipCutterdoes every edit without the window: the parts of the clip (start, end, speed, volume, mute), gaps left by Delete, the blade, edge trims that take back or cut away, music on A2, fades, Remove silence and undo / redo (one step per drag). The result is aClipEdit, unit tested on its own.ClipWindowViewModelholds the window's state: the overview of the whole video (Controls/ClipTimeline: 16 frames, the loudness, the handles) and the sequence under it (Controls/ClipSequence: V1 pictures, A1 the video's sound, A2 music). Both are custom-drawn controls; their pictures and loudness are taken again only when the clip's ends rest.- Space plays the clip as it will be written:
Engines/Media/ClipPreviewruns the same filter graph as the output, the pictures as raw BGRA frames over a pipe and the sound throughffplay(when it sits next to Filee's FFmpeg; without it the preview is silent). FFmpeg for the window runs below normal priority. - Save calls
ClipTool.ConversionOf, which carries theClipEditinMediaOptions.Clip, so the toast, cancel, the output rules ({name}_clipnext to the video) and the history work as for any conversion.FfmpegConvertercopies one plain stretch with-ss/-toand-c copy(Fast, no re-encoding), or encodes the exact cut. - Anything else is one filter graph (
MediaEncoding.ClipGraphOf): the video is read once,split/trimper piece,setptsand chainedatempofor speed,volume,color/anullsrcfor gaps,concat, the music as a second input (atrim,volume,afade,adelay,amix), thenfade/afade. It is encoded with the preset's quality, size and codec.
"Crop video" (crop-video, after Cut a clip on the back of the video donut, #830) is a group of ordinary
conversions, not a window: each preset keeps the video's own format (MP4 for VOB and DV, whose fixed frame sizes would
stretch the crop back: VideoCrop.TargetFor) and sets MediaOptions.CropFrame to auto or a width:height ratio
(Core/Presets/VideoCrop).
- A ratio crops the largest centred box of the upright picture with square pixels (
MediaEncoding.RatioBox); a video already that shape is refused (error.crop_same_frame). - Auto runs
cropdetect(limit as a part of the range, so 10-bit and HDR read alike) over a second at five points of the video (the first five seconds of a short one), takes each stretch's final box and the largest of those (MediaEncoding.FinalCrop,LargestCrop); no black bars, or a box under a quarter of the picture, refuses the file (error.no_black_bars), and cropdetect failing everywhere is an error with FFmpeg's message. - The crop goes before the scale filter, so the video is always encoded: an HEVC or AV1 source stays in its codec where the target and FFmpeg allow it (keeping 10 bits and HDR tags), the sound is copied where the container takes it, and an MKV keeps its subtitles and attachments.
The tool-sheet-studio tool opens an independent Views/SpreadsheetPrintStudioWindow for each dropped XLSX workbook
instead of starting a normal conversion job. SpreadsheetPrintStudioViewModel owns an ordered, non-destructive print plan: each visible
sheet starts as one region and the user can add more regions, change paper, orientation, scale, margins, page order,
hidden rows and manual breaks, then see the PDF that those settings will produce.
SpreadsheetPrintInspectorreads workbook metadata and streams the large worksheet data withXmlReader; opening a large workbook neither builds nor retains anXDocumentfor every sheet.SpreadsheetPrintPackagemakes a disposable XLSX underJobQueue.DefaultWorkRoot. It keeps every worksheet and named range so cross-sheet formulas remain valid, hides the sheets not being rendered, and changes only the chosen sheet's print settings. A new print area is written only after the user explicitly changes or accepts the range.SpreadsheetPrintServiceruns LibreOffice once for each region. Preview and export use the same disposable-workbook path; export then joins the region PDFs in the chosen order with PDFsharp. The ordinary XLSX → PDF donut conversion can still differ because route planning may select Filee's built-in spreadsheet reader instead of LibreOffice.PdfPreviewDocumentcaches a PDF's bytes and page geometry. The studio asks PDFium/PDFtoImage for small thumbnails and only one large selected page, all decoded away from the UI thread; exporting never performs preview rendering. Cancellation closes LibreOffice and the temporary job folder is removed on success, error or window close.
UserDataStore owns settings.json, presets.json, profiles.json and history.json
(System.Text.Json source generation, atomic writes, broken files are kept as *.broken).
Bump AppSettings.CurrentSchemaVersion and add a step to SettingsMigrations when the format changes.
LocalizationServiceloadsAssets/i18n/<lang>.jsonintoApplication.Resources; XAML uses{DynamicResource key}, so switching language updates the UI live.ThemeServicewrites the accent colour, corner radii, fonts, the reading direction and Fluent'sSystemAccentColor*into application resources. Arabic reads right to left:Styles/Soft.axaml's Window style takesFlowDirectionfrom that resource, so every window mirrors; the donut, the crop canvas and animated images stay left to right. Light/dark surface colours are theme dictionaries inStyles/Soft.axaml; a user'stheme.json(CustomTheme, see CUSTOM-THEMES.md) overrides them with theme dictionaries in application resources, which are searched first.- What sits on an accent fill is
OnAccentBrush: white or dark, whichever has the higher WCAG contrast (SoftPalette.OnAccent).SoftPalette.ApplyAccentStatesalso gives Fluent's accent controls this label instead of their fixed white, and their hover and pressed fills, which move away from the label when they would cost it contrast. New text onAccentBrushtakesOnAccentBrush, never a fixed colour. - Window zoom (
Services/UiZoom): Theme → Window size (− / + and Reset), and in any tracked window the platform's command key (HotkeyConfiguration.CommandModifiers: Ctrl, Cmd on macOS) with the mouse wheel, plus / minus (Shift allowed, Alt not: AltGr is Ctrl + Alt) or 0 for 100 %. 70–180 % in 10 % steps, every window at once.UiZoom.Track(window)wraps the window's content in aLayoutTransformControl, so layouts see the room they really have. Small wheel deltas (touchpads, smooth wheels, pinching on a Windows touchpad) add up to one step per whole notch. Windows that can't be resized grow with the zoom (their designed width × the zoom) up to their screen, cap their height to it and scroll; the engine setup keeps itself on screen and scrolls its own list (fitsItself). Tracked: the main window, the preset, group, rename and merge-order editors, the engine setup, LibreOffice options, close, sponsor, what's new and update-progress windows andWindowService's message dialog. Not tracked, so at 100 %: the donut (it has its own size), the toast and the corner notices (update, engine update, feedback, format request, elevation), which are placed in a screen corner like system notifications, and the crop overlay, whose wheel zooms the crop. Drop-down lists, context menus and tooltips open in their own popup windows outside the transform and stay at 100 % too. The size isUiScalein settings.json (1 when missing, so no schema step); it is written byUserDataStore.SaveUiScale0.6 s after the last change (and on exit), without raisingSettingsChanged.
After an update, Filee shows the new version's features once as slides (an animation or picture, a title, a line or two). The pieces:
Assets/WhatsNew/<version>/slides.jsonlists the slides:id,media(a file next to it), and the i18n keys oftitleandtext(whats_new.<version>.<id>.title, in every language file).SlideDeck(Controls) reads every manifest from the assembly's resources; a broken one is skipped.AnimatedImageshows GIF, animated WebP or a still picture. Avalonia'sImageshows only the first frame, soAnimatedImageDecoderdecodes frames with Skia'sSKCodec, which also says which earlier frame each one is drawn over (RequiredFrame, disposal included). The file is copied into anSKDataand each frame is decoded straight into aWriteableBitmap's framebuffer: no managed buffer is ever handed to native code.FrameTimelinekeeps the frame durations (0–10 ms counts as 100 ms, as in browsers) and the loop count. The animation pauses while the control is hidden or its window is minimized, shows the first frame with reduced motion (AutoPlay), and gives the decoder and bitmap back when it leaves the visual tree or its source changes.SlideShowis the deck itself (picture, texts, position dots), built in code soFilee.Setupcan link the same files for a slideshow on its progress page (AutoAdvance). All slides' texts sit in one grid cell, only the current one visible, so the height is the tallest slide's and the window doesn't jump.WhatsNewWindowadds the card, ✕, Previous / Next ("Get started" on the last slide), ←/→ and Esc.WhatsNewServicedecides at start-up, before the first run is marked complete:- a fresh install (first run not completed) needs no slides, as the first-run setup introduces Filee; its version is stored as seen;
- otherwise
AppSettings.WhatsNewSeenVersion(null in settings older than the slides, which means "updated") is compared with the running version, and the newest deck after it, up to this version, is shown; - the same version or a downgrade shows nothing and never lowers what was seen; an update without a deck is
stored as seen quietly.
The version is stored when the window opens. A start in the background (
--backgroundat sign-in, or the Explorer menu) keeps the deck untilWindowService.ShowMainraisesMainShown; the installer starts an updated Filee with--background --whats-new, which shows it at once. About → "What's new in Filee X" opens the newest deck again.
The <!-- update --> lines of CHANGELOG.md are the other half: the update card shows them for a version that isn't
installed yet; the slides introduce the installed one. The demo animations are rendered by
tests/Filee.App.Tests/WhatsNewMedia.cs from the real windows (see CONTRIBUTING.md, "Releasing").
Filee.Cli(filee-cli.exe, run asfileethroughcli\filee.cmd, which Setup can put on PATH) composes the same pipeline as the app without any UI (CliHost:UserDataStore,EngineRegistry,ConverterCatalog,JobQueue) and reads the app's presets and engine order. It is published into the app folder, so both share one runtime and the bundled engines; its name can't befilee.exenext toFilee.exeon a case-insensitive file system. When invoked with--notify(or from Explorer context menu executions),NativeToastinvokes the native Windows Action Center notification with conversion outcomes and file paths, completely headless with zero resident RAM. To eliminate console window popups from Explorer verbs, a 4 KB native GUI launcher (filee-run.exe, compiled withIMAGE_SUBSYSTEM_WINDOWS_GUI) triggers the WindowsIDC_WAITloading cursor and invokesfilee-cli.exewithCREATE_NO_WINDOWandSW_HIDE, returning the cursor to normal upon completion.Filee.Core/Watching/FolderWatcherwatches oneWatchRulewith aFileSystemWatcherand converts a file once it has kept its size and time for a moment, opens without sharing and has data at its start (downloads and copies in progress are skipped). A file that didn't convert gets one more turn after 10 seconds. Temporary files, unknown formats and dedicated output and originals folders are ignored. Links (junctions, mount points, symbolic links to folders or files) are never followed or converted, neither as they arrive, nor in the scan of what is already there (FolderWatcher.FilesInside), nor when a file gets its second turn; other reparse points, such as OneDrive's online-only files, are converted like any file. A rule may also write into the watched folder itself. In that case, generated file versions (path, size and modification time) and generated result directories are recorded in.filee-watch-<rule hash>.jsoninside the watched root. The hidden state file prevents those results from becoming new inputs, including after an inbox watcher restarts; a changed file with an old output name is accepted again. A failure to save this state is logged because results may be retried after restart. Removing a rule's state file also forgets its results. The tray app runs one per rule (WatchFolderService, Settings → Watch folders, conversions in the toast and history);filee watchruns one on its own, with a stableclirule identity across command restarts.
Everything OS-specific goes through IPlatformServices (Filee.Core/Platform). Windows lives in
Filee.Platform.Windows; macOS will get its own project. Global input uses SharpHook on both.
Home → Recent conversions opens a result with OpenFile (the shell on Windows, open on macOS, xdg-open on Linux,
so a file is handed to its app and never started itself; only formats Filee knows are offered) and, where
SupportsOpenWith (Windows), the shell's "Open with" dialog (SHOpenWithDialog, on a thread of its own because it
blocks until closed). The cards' pictures come from HistoryThumbnails: Skia decodes them off the UI thread, scaled
down while decoding where the format allows, from a copy read in one go so the file isn't held open, and a small cache
keeps them while the files are unchanged. For video files, FFmpeg extracts and scales a representative frame off the UI thread without locking the file.
On macOS, files reach Filee from file managers other than Finder too (issue #160). The "Convert with Filee" service
(MacOSServicesProvider) and the donut's drags (DraggedFiles) read file URLs first, then the older
NSFilenamesPboardType array of paths (PasteboardPaths); the service also takes plain-text lines that are absolute
paths. The donut registers those types with AppKit next to Avalonia's own, so such a drag reaches it, and a drag or
service request without readable files is logged with the types it offered. File promises (NSFilePromiseProvider)
can't be received through Avalonia; for a browser drag Filee reads the address and HTML it also offers, which the donut
registers too (see "Files dragged from a web browser"). A click-mode donut opened for a later launch or the service forgives one loss of
focus within a second of opening (ActivationGrace): Filee becoming the active app can take focus away from it.
A keyboard shortcut with TriggerGesture.Clipboard reads the clipboard instead of the selection
(IPlatformServices.ReadClipboard, MacOSClipboard): copied files (file URLs, then NSFilenamesPboardType; copied
files that are gone give nothing, not Finder's icon), else a picture (PasteboardPaths.PictureTypes, PNG first, TIFF
last). With neither on the clipboard the shortcut does nothing — it never falls back to the file manager's selection,
which for an Everywhere shortcut could sit in a Finder window in the background. A picture becomes a one-item WebDrop
with SaveOnlyConverted, so it is saved into the browser-drop folder when it converts and only the result stays. The
donut's jobs are started with toClipboard, and ConversionService puts their outputs back on the clipboard when they
finish (CopyToClipboard: a file URL per item, a single picture also as itself; the log also carries how many files
failed). No shortcut has Clipboard on by default and no settings migration adds one: the global hook can't hold the
keys back, so a preset combination would also reach the app in front (Shift + Cmd + V is Paste and Match Style in most
text fields). Whoever wants it turns the switch on in Settings → Shortcuts for a shortcut with keys of their own choosing.
The donut, the toast and the notices are transparent windows. On Windows Filee keeps Avalonia's rendering defaults
(ANGLE on Direct3D 11 composed through WinUI composition, then DirectComposition, then the window's redirection
surface; software rendering when Direct3D 11 fails): each of them keeps per-pixel transparency. The log says what was
picked (Rendering: AngleEgl with WinUIComposition), lists the graphics adapters, carries Avalonia's own errors from
starting the GPU paths (AvaloniaLogForwarder), and describes each kind of transparent window the first time it
shows (TransparentWindows). A system backdrop (Acrylic, Mica) or an accent blur on such a window turns its
transparent area into a blurred rectangle (issue #269). Filee sets neither, so one found there came from another
program: each time the window shows, a backdrop is set back to none and the accent (which can't be read back) is
turned off. For a report that still shows the wrong thing, the FILEE_RENDERING environment variable picks another
way to draw (WindowsRendering): dcomp (skip WinUI composition), redirection (Direct3D into the redirection
surface) or software (no GPU); unset or auto keeps the defaults. Filee reads it at start. On ARM64, Avalonia's
Adreno blocklist draws on the CPU through the Microsoft Basic Render Driver (issue #236), and three values try the GPU
there again: gpu (Direct3D on the first adapter that isn't the Basic Render Driver), vulkan and wgl (OpenGL), the
last two falling back to software when they can't start. On Linux (X11) only software applies: the GPU's driver stays
in memory for as long as Filee runs, also with no window open, so this is the way to a smaller tray app (issue #957).
Settings → General → "Show “Convert with Filee” in the Explorer context menu" (AppSettings.ContextMenuEnabled) is
applied by WindowsPlatformServices.SetContextMenu at start-up and whenever settings change (installed builds only):
- Classic verb
HKCU\Software\Classes\*\shell\Filee(Filee.exe --convert "%1",MultiSelectModelPlayer) and a Send To shortcut. Per user, no admin rights. On Windows 10 this is the entry; on Windows 11 it sits under "Show more options". Explorer starts one process per selected file, out of order and over many seconds, and hides the entry above 100 files (Send To has no such limit). The processes reach the running instance throughSingleInstance; the first asks Explorer for the selection, so the donut has all of it at once (SelectionLaunches). When that can't be read (another file manager), they are collected for 350 ms and later ones join the open donut (RadialController.TryAddFiles); once a conversion took its files, later ones get a donut of their own. - Windows 11 top-level entry (optional): an
IExplorerCommandinFileeExplorerMenu.dll(src/Filee.ExplorerMenu, plain C, no C runtime) declared by the sparse packageFileeExplorerMenu.msix(ExplorerMenuPackage.CreateManifest:desktop4:FileExplorerContextMenus,desktop5:ItemType Type="*",com:SurrogateServer,uap10:AllowExternalContent,AppListEntry="none"). Both files ship next to Filee.exe and the package's external location is the install folder (C:\Program Files\Fileeby default).- The package is unsigned (publisher contains
OID.2.25.311729368913984317654407730594956997722=1; Filee has no code-signing certificate). Windows only registers an unsigned package with executable content with administrator rights (it installs it for all users); a per-user attempt fails with 0x80073D2B "an unsigned package cannot include Executable activations". Setup (src/Filee.Setup) has those rights anyway and registers it on Windows 11 x64 while its option is ticked. Later the General page offers "Add to the main menu", which runsAdd-AppxPackage -Path … -ExternalLocation … -AllowUnsignedin Windows PowerShell through one UAC prompt (ExplorerMenuRegistration). A signed package would register per user without a prompt. - The manifest version (
ExplorerMenuPackage.ManifestVersion) is independent of the app version, so app updates don't need a new prompt: the DLL is loaded from the install folder and updated with the app. Bump it only when the manifest changes; the page then offers to add the entry again ("Outdated"). - The DLL shows the entry only for files (not folders or items inside ZIP folders) and only while
%APPDATA%\Filee\explorer-menu.txtexists. The app writes the title in the UI language there while the setting is on and deletes it when the setting is off, so switching the setting takes effect without re-registering. While the package is registered the classic verb is removed (Windows lists packaged commands under "Show more options" too). - Cascading submenus (
IEnumExplorerCommand+IObjectWithSelection): The DLL inspects the selected items' file extensions and populates a cascading submenu dynamically tailored to the target format category:- Images (
.png,.jpg,.jpeg,.webp,.bmp,.gif,.svg): JPEG, PNG, WebP, PDF - Documents (
.md,.txt): PDF, Word (.docx), HTML - Spreadsheets (
.xlsx,.xls,.ods,.csv): CSV, Excel (.xlsx) - PDF (
.pdf): Images (.png), Word (.docx), Markdown (.md), Plain Text (.txt) - Data (
.json,.yaml,.toml,.xml): JSON, YAML, TOML, CSV Unsupported files and mixed categories returnECS_HIDDEN.
- Images (
- Invoke starts
filee-cli.exe convert "<path>"... --to <fmt> --quiet --notifynext to the DLL withSW_HIDE/CREATE_NO_WINDOWand returns at once (0 background RAM). Selections longer than a command line go through%TEMP%\Filee-convert-*.txtpassed as@<listfile>, whichfilee-cliparses natively. Notifications are delivered via native Win32 toast. - Updates: Setup asks the running Filee to exit (
Filee.exe --quit), then renames aFileeExplorerMenu.dllthat Explorer still has loaded into its backup folder (Windows allows renaming a loaded DLL, not replacing or deleting it) and has Windows delete the old copy at the next restart, so updating needs no restart. An update keeps the registration as it was and refreshes it. Uninstall runsFilee.exe --uninstall-cleanup(UninstallCleanup): it removes the package, the title file, the classic verb, the startup entry and downloaded engines; the uninstaller then asks whether to delete the settings too (they stay by default). - Build:
pwsh build/build-explorer-menu.ps1downloads a pinned Zig (SHA-256 checked) intobuild/.cache, compiles
- The package is unsigned (publisher contains
Filee registers two context menu mechanisms on Windows:
-
Windows 11 Modern Context Menu (
FileeExplorerMenu.dll):- Freestanding native C COM extension implementing
IExplorerCommandHandler. - Packaged with an unsigned sparse MSIX manifest generated on-the-fly via
build/tools/make-explorer-package.cs. - Queries file selection, builds dynamic submenus, and dispatches execution to
filee-run.exe.
- Freestanding native C COM extension implementing
-
Windows 10 / Classic Context Menu (
filee-run.exe):- Zero-admin cascading submenus registered in
HKCU:\Software\Classesacross 5 file categories (Images, Documents, Spreadsheets, PDF, Data). - Launches
filee-run.exewhich triggers theIDC_WAITmouse loading spinner and invokesfilee-cli.exesilently in the background (CREATE_NO_WINDOW).
- Zero-admin cascading submenus registered in
Filee provides two official release distribution formats produced by build/build-release.ps1:
-
Filee-Setup.exe(1-Click Zero-Admin Installer):- Built from
src/Filee.Setup/setup.candsetup.rcusing MinGW GCC andwindres. - Embeds the official application icon and a compressed self-contained payload archive as an
RT_RCDATAresource. - Requires zero administrator rights. Installs to
%LOCALAPPDATA%\Programs\Filee. - Extracts the payload via Windows native
tar.exeinto the destination. - Automatically executes
filee-cli.exe install --quiet, registering context menus, Windows 11 sparse package, UserPATH, and Windows Settings (HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Filee). - Supports non-interactive / silent execution with
/S,/s,--silent, or--quiet.
- Built from
-
Filee-win-x64.zip(Portable Package):- Self-contained, portable zip archive that can be extracted anywhere.
- Contains
install.cmdanduninstall.cmdhelper scripts for instant in-place context menu and PATH registration.
-
Automated CI/CD Workflow (
.github/workflows/release.yml):- Triggers on tag pushes matching
v*. - Compiles native components, publishes self-contained win-x64 binaries, runs the test suite, bundles the installer and portable archive, and publishes them to GitHub Releases with SHA-256 manifests.
- Triggers on tag pushes matching