lame

Newcomer Guide

This guide is for readers who may be new to Swift, SwiftUI, macOS desktop apps, or Apple’s device access frameworks.

What This App Is In Plain Language

Lame is a desktop app that shows photos and videos stored on a USB-connected iPhone. It lets the user browse those files, search them, sort them, filter them, and delete selected items.

At a high level, the app has three parts:

1. A device communication layer that talks to the iPhone.
2. A model layer that reshapes raw framework objects into app-friendly objects.
3. A user interface layer that renders lists, grids, and controls.

The Smallest Useful Mental Model

If you only remember one thing about this project, remember this:

• DeviceManager talks to the system framework and owns shared state.
• MediaFile wraps one file from the iPhone.
• ContentView chooses what main screen to show.
• MediaGridView is the main browser interface.
• MediaItemView renders one visual tile.

That is the backbone of the project.

How A SwiftUI App Differs From A Traditional Desktop App

In many older UI frameworks, you manually tell views when to redraw.

SwiftUI works differently:

• Views describe what the UI should look like for the current state.
• When the state changes, SwiftUI recalculates the view output.
• The framework figures out how to update the visible interface efficiently.

That means understanding this codebase mostly comes down to understanding where state lives.

Where State Lives In This Project

There are two main kinds of state in the app.

Shared application state

This lives in DeviceManager and includes things like:

• what devices are connected
• which device is selected
• which files were loaded from the device
• whether the app is still loading
• whether a delete operation is running
• whether there is an error to show

Temporary screen state

This lives in MediaGridView and includes things like:

• which items are selected in the grid
• the current sort field and sort direction
• the active filter values
• the search text
• the current thumbnail size

This split is intentional. It prevents temporary UI concerns from leaking into the system integration layer.

What @Observable Means Here

@Observable is a Swift feature that makes objects easier for SwiftUI to watch.

When a property on an observable object changes, views that read that property can update automatically.

In this project:

• DeviceManager is observable, so views react when device or file state changes.
• MediaFile is observable, so individual grid cells react when a thumbnail finishes loading.

Why There Is A Wrapper Around ICCameraFile

The iPhone files come from Apple’s ImageCaptureCore framework as ICCameraFile objects.

Those objects are usable, but not ideal for the app’s UI needs. The wrapper class MediaFile adds:

• a SwiftUI-friendly identity
• thumbnail state
• loading state for thumbnails
• convenience properties such as formatted file size and media type

That makes the rest of the app simpler.

How Data Moves Through The App

Here is the normal runtime path:

1. The app launches.
2. LameApp creates a shared DeviceManager.
3. DeviceManager starts browsing for connected camera-like devices.
4. The sidebar shows discovered iPhones.
5. The user picks a device.
6. DeviceManager opens a session and reads the media catalog.
7. The app converts raw framework files into MediaFile values.
8. MediaGridView displays those files.
9. MediaItemView requests thumbnails as cells appear.

How To Read The Source If You Do Not Know Swift

Read in this order:

1. README.md
2. docs/Architecture.md
3. docs/Project-Structure.md
4. Lame/LameApp.swift
5. Lame/ContentView.swift
6. Lame/MediaFile.swift
7. Lame/DeviceManager.swift
8. Lame/MediaGridView.swift
9. Lame/MediaItemView.swift

That order moves from simple high-level structure to detailed behavior.

How To Read Swift Syntax In This Repository

Some recurring patterns are worth knowing.

struct Something: View

This means a SwiftUI view definition. Think of it as a reusable screen or component.

var body: some View

This is the rendered UI definition for a SwiftUI view.

@State

This means the view owns a piece of temporary local state.

@Environment(DeviceManager.self)

This means the view reads a shared object that was inserted higher up in the app.

if ... else inside body

This means the UI changes based on state, for example loading versus empty versus grid display.

Task { ... } and async

This means the code is doing asynchronous work, such as waiting for the device or a thumbnail request.

Why The Code Contains So Many Comments

The main complexity in this project is not the visible UI. It is the adaptation between:

• a modern declarative UI framework
• an older callback-oriented system framework
• asynchronous device operations

The comments aim to make those boundaries explicit so a reader does not need deep prior Swift knowledge to follow the design.

If You Only Need To Change One Kind Of Behavior

• To change startup or global wiring, look at LameApp.swift.
• To change the app window structure, look at ContentView.swift.
• To change device communication, look at DeviceManager.swift.
• To change grid layout or selection behavior, look at MediaGridView.swift.
• To change the look of one media tile, look at MediaItemView.swift.
• To change sorting or filtering options, look at SortOptions.swift and SizeRangeFilter.swift.

Common Questions A New Reader Might Ask

Why is there one shared manager instead of each view talking to the device?

Because the device layer has session management, callbacks, timeouts, and cancellation concerns. Centralizing that in one place keeps the UI readable.

Why are some things classes and others structs?

• MediaFile and DeviceManager are classes because they represent shared observable reference state.
• Many UI configuration and filter types are structs or enums because they are small values that are easy to copy.

Why do thumbnails load later instead of all at once?

Because loading every thumbnail from the device immediately would be slower, heavier, and more complex. The app only requests thumbnails for visible cells.

Recommended Next Reading

After this guide, the best next files are:

1. docs/Glossary.md
2. docs/Design-Diagrams.md
3. docs/Full-Documentation.md

This site is open source. Improve this page.