Attachments Formats and Filenames

Attachments, Formats, and Filenames

Unspool is intentionally format-agnostic. The browser does not contain an allowlist that rejects unfamiliar extensions.

Telegram representations

The TDLib mapping layer recognizes media delivered as:

• document;
• audio or music;
• voice message;
• video;
• video note;
• animation;
• photo or image;
• sticker;
• another supported message-content representation.

Music sent through Telegram's music UI is still mapped as an attachment. A FLAC music item is not excluded merely because it was not sent with the generic file button.

Filename provenance

AttachmentFilename.resolve uses this precedence:

1. the original filename from the Telegram media object;
2. a usable filename from Telegram's file representation;
3. a neutral deterministic fallback when Telegram supplies neither.

The fallback format is:

unnamed-<media-kind>-<message-id>.<preferred-extension>

The extension is omitted when it is unknown. This fallback is not presented as an original filename: the domain value records whether its provenance is telegramOriginal, telegramFile, or generated.

Unspool never synthesizes a filename from:

• music artist;
• track title;
• album;
• caption;
• embedded tags;
• chat title.

That rule matters because metadata can be edited independently from the file and can destroy the uploader's naming scheme.

Filename preservation and filesystem safety

The original filename is preserved exactly at the domain boundary, including case and Unicode. Before placement, the destination layer rejects names that are unsafe as a single macOS path component. It does not silently sanitize an unsafe Telegram name into a different name.

The chat title may be sanitized for the optional directory name because that directory is an organizational container, not the attachment's filename.

Extension badges

Every row uses the same neutral thumbnail component. It displays the final filename extension in uppercase:

• FLAC
• LRC
• PNG
• MOV
• any other available extension

If the filename has no extension, the badge displays FILE. Media artwork and image thumbnails are intentionally not mixed into this component, keeping rows stable across file types.

Categories

Categories help browsing; they do not control eligibility:

• Audio
• Video
• Images
• Documents
• Other

Known extensions are classified first. When an extension is unknown, the TDLib media kind provides the category. This means an unfamiliar extension remains visible even when the app cannot classify it more specifically.

Attachment identity and eligibility

An attachment identity combines the Telegram chat ID, message ID, and file ID. Eligibility can be:

• eligible;
• alreadyDownloaded;
• queued;
• unavailable.

The original filename is never used as the identity because different Telegram files can legitimately share one name.