Skip to content

Latest commit

 

History

History
532 lines (472 loc) · 48.6 KB

ARCHITECTURE.md

File metadata and controls

532 lines (472 loc) · 48.6 KB

Architecture

           ┌───────────────────── 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        │
           └────────────────────────────────────────────────────────────────────┘

Flow of a Conversion

  1. Trigger – The user right-clicks a file in File Explorer and selects a conversion target from the cascading submenu, or invokes filee-cli.exe directly.
  2. Launch & Visual Feedback – On Windows Explorer clicks, filee-run.exe instantly turns the cursor into the IDC_WAIT hour-glass/spinner and launches filee-cli.exe completely hidden (without console flash).
  3. Plan – RoutePlanner uses Dijkstra's algorithm over registered converter edges to compute the shortest conversion graph from source to target (maximum 3 hops).
  4. Run – JobQueue executes converter steps with concurrency control. Intermediate files live in private user temporary folders (WorkFolders.Root); final outputs are placed by OutputPathResolver.
  5. Completion & Notification – When invoked with --notify, Filee.Cli delivers 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.
  6. Report – progress and results appear in the toast window and in Home → Recent conversions. Renderers check only the original source for referenced fonts. ConversionStep.MissingFonts reports any missing families to FileResult.MissingFonts; the toast card can offer one trusted source, while the CLI and watch jobs report the names without pausing conversion or installing anything.

Files dragged from a web browser

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_DIR on Linux, ~/Downloads on 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 Release deletes 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, localhost and .local names, IPv4 inside IPv6) is refused (error.web_local_address), on every redirect and after the name is looked up: the handler's ConnectCallback connects 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 an HttpClient of 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 (.jpg that 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 a Zone.Identifier stream as a browser's download would (ZoneId=3, and HostUrl with 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. JobQueue copies 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.

Donut control

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" (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's AnnotationCanvas calls it on Avalonia's own Skia canvas (a custom draw operation through ISkiaSharpApiLeaseFeature), scaled to where the picture is shown, and Annotator on layers over the part the marks cover, a band at a time, laid over the picture in ImageEncoder.ApplyOptions after 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.
  • AnnotationSet keeps 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; ReworksPixels includes the marks.

Add background tool

"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 with ImageOptions.Backdrop, run by the job queue like Pixelate / blur's areas: ReworksPixels includes it, so it is applied once, in the first transform step. The tool keeps the last look apart, in ImageOptions.BackdropLook; an export or import leaves out the path of a picture of one's own.
  • Engines/Magick/BackdropComposer composes it in ImageEncoder.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.
  • BackgroundViewModel draws 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.

Crop overlay and PDF page editor

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.

  • CropOverlayViewModel walks the queue (Enter saves and opens the next file, Skip, Esc closes), keeps a CropQueueItem per 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/CropCanvas is the stage: the picture inside ImagePadding, 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 within CropMath.SnapDistance (8 px) and shows that line as a dashed guide until the drag ends. The preview is downscaled once by CropService.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, and PlayAnimations (from Motion.Enabled) turns all of it off.
  • Controls/AspectDial is a small donut of the ratios (free, original, 1:1, 5:4, 4:3, 3:2, 16:9): each slice a RingSegment button 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. AspectGlyph is the dial in miniature on that button, and CropSummaryRing the end summary's donut (a slice per file).
  • Controls/CropMath holds 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.

Clip window

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/ClipCutter does 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 a ClipEdit, unit tested on its own.
  • ClipWindowViewModel holds 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/ClipPreview runs the same filter graph as the output, the pictures as raw BGRA frames over a pipe and the sound through ffplay (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 the ClipEdit in MediaOptions.Clip, so the toast, cancel, the output rules ({name}_clip next to the video) and the history work as for any conversion. FfmpegConverter copies one plain stretch with -ss/-to and -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/trim per piece, setpts and chained atempo for speed, volume, color/anullsrc for gaps, concat, the music as a second input (atrim, volume, afade, adelay, amix), then fade/afade. It is encoded with the preset's quality, size and codec.

Crop video

"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.

Spreadsheet print studio

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.

  • SpreadsheetPrintInspector reads workbook metadata and streams the large worksheet data with XmlReader; opening a large workbook neither builds nor retains an XDocument for every sheet.
  • SpreadsheetPrintPackage makes a disposable XLSX under JobQueue.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.
  • SpreadsheetPrintService runs 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.
  • PdfPreviewDocument caches 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.

Settings and data

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.

Localization and theming

  • LocalizationService loads Assets/i18n/<lang>.json into Application.Resources; XAML uses {DynamicResource key}, so switching language updates the UI live.
  • ThemeService writes the accent colour, corner radii, fonts, the reading direction and Fluent's SystemAccentColor* into application resources. Arabic reads right to left: Styles/Soft.axaml's Window style takes FlowDirection from 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 in Styles/Soft.axaml; a user's theme.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.ApplyAccentStates also 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 on AccentBrush takes OnAccentBrush, 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 a LayoutTransformControl, 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 and WindowService'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 is UiScale in settings.json (1 when missing, so no schema step); it is written by UserDataStore.SaveUiScale 0.6 s after the last change (and on exit), without raising SettingsChanged.

"What's new" slides

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.json lists the slides: id, media (a file next to it), and the i18n keys of title and text (whats_new.<version>.<id>.title, in every language file). SlideDeck (Controls) reads every manifest from the assembly's resources; a broken one is skipped.
  • AnimatedImage shows GIF, animated WebP or a still picture. Avalonia's Image shows only the first frame, so AnimatedImageDecoder decodes frames with Skia's SKCodec, which also says which earlier frame each one is drawn over (RequiredFrame, disposal included). The file is copied into an SKData and each frame is decoded straight into a WriteableBitmap's framebuffer: no managed buffer is ever handed to native code. FrameTimeline keeps 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.
  • SlideShow is the deck itself (picture, texts, position dots), built in code so Filee.Setup can 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.
  • WhatsNewWindow adds the card, ✕, Previous / Next ("Get started" on the last slide), ←/→ and Esc.
  • WhatsNewService decides 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 (--background at sign-in, or the Explorer menu) keeps the deck until WindowService.ShowMain raises MainShown; 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").

Command line and watch folders

  • Filee.Cli (filee-cli.exe, run as filee through cli\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 be filee.exe next to Filee.exe on a case-insensitive file system. When invoked with --notify (or from Explorer context menu executions), NativeToast invokes 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 with IMAGE_SUBSYSTEM_WINDOWS_GUI) triggers the Windows IDC_WAIT loading cursor and invokes filee-cli.exe with CREATE_NO_WINDOW and SW_HIDE, returning the cursor to normal upon completion.
  • Filee.Core/Watching/FolderWatcher watches one WatchRule with a FileSystemWatcher and 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>.json inside 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 watch runs one on its own, with a stable cli rule identity across command restarts.

Platform code

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).

Explorer integration

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", MultiSelectModel Player) 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 through SingleInstance; 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 IExplorerCommand in FileeExplorerMenu.dll (src/Filee.ExplorerMenu, plain C, no C runtime) declared by the sparse package FileeExplorerMenu.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\Filee by 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 runs Add-AppxPackage -Path … -ExternalLocation … -AllowUnsigned in 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.txt exists. 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 return ECS_HIDDEN.
    • Invoke starts filee-cli.exe convert "<path>"... --to <fmt> --quiet --notify next to the DLL with SW_HIDE / CREATE_NO_WINDOW and returns at once (0 background RAM). Selections longer than a command line go through %TEMP%\Filee-convert-*.txt passed as @<listfile>, which filee-cli parses natively. Notifications are delivered via native Win32 toast.
    • Updates: Setup asks the running Filee to exit (Filee.exe --quit), then renames a FileeExplorerMenu.dll that 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 runs Filee.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.ps1 downloads a pinned Zig (SHA-256 checked) into build/.cache, compiles

Windows Explorer Integration

Filee registers two context menu mechanisms on Windows:

  1. 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.
  2. Windows 10 / Classic Context Menu (filee-run.exe):

    • Zero-admin cascading submenus registered in HKCU:\Software\Classes across 5 file categories (Images, Documents, Spreadsheets, PDF, Data).
    • Launches filee-run.exe which triggers the IDC_WAIT mouse loading spinner and invokes filee-cli.exe silently in the background (CREATE_NO_WINDOW).

Release Packaging & Automated Installation

Filee provides two official release distribution formats produced by build/build-release.ps1:

  1. Filee-Setup.exe (1-Click Zero-Admin Installer):

    • Built from src/Filee.Setup/setup.c and setup.rc using MinGW GCC and windres.
    • Embeds the official application icon and a compressed self-contained payload archive as an RT_RCDATA resource.
    • Requires zero administrator rights. Installs to %LOCALAPPDATA%\Programs\Filee.
    • Extracts the payload via Windows native tar.exe into the destination.
    • Automatically executes filee-cli.exe install --quiet, registering context menus, Windows 11 sparse package, User PATH, and Windows Settings (HKCU\Software\Microsoft\Windows\CurrentVersion\Uninstall\Filee).
    • Supports non-interactive / silent execution with /S, /s, --silent, or --quiet.
  2. Filee-win-x64.zip (Portable Package):

    • Self-contained, portable zip archive that can be extracted anywhere.
    • Contains install.cmd and uninstall.cmd helper scripts for instant in-place context menu and PATH registration.
  3. 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.