How Atmos Handles Built-In vs Uploaded Content

Atmos is not just a loose file picker with a playlist attached.

Under the hood, the app has two different content sources working side by side:

• built-in media that ships with the app
• uploaded media that the user adds locally

Both end up appearing in the Atmos library, but they are not treated exactly the same way. This guide explains how the two content types differ, how the app decides what a profile can do, and which hidden behaviors matter once you start building a real Atmos setup.

Built-in and uploaded items both become profiles

Atmos uses a common profile model for library items.

That means built-in content and uploaded content can both show up as profiles with properties like:

• name
• media type
• local path
• video mode
• artwork
• creation date

This shared structure is useful because it lets the app render and manage the library consistently.

Built-in content is seeded by the app

Atmos ships with a small built-in media library that includes:

• audio tracks
• image backgrounds
• video backgrounds

On launch, after saved profiles are loaded, Atmos checks whether the built-in entries it expects are already present. If any current built-in item is missing, the app adds it back into the profile list.

That means the built-in library is not just bundled assets sitting somewhere on disk. It is actively seeded into the user-facing profile system.

Hidden behavior: stale built-in entries are cleaned up

Atmos also removes built-in profile entries if they point to bundle items that are no longer part of the current app bundle.

That matters because it keeps old renamed or removed built-in content from lingering forever as broken entries after updates.

So the built-in library is not only appended. It is also reconciled.

Built-in media uses bundle: paths

One of the most important technical details is that built-in profiles do not rely on ordinary raw file paths.

Instead, their stored path uses a bundle: prefix.

Atmos later resolves that bundle reference dynamically back to the actual resource inside the current app bundle.

This is a smart design choice because it lets built-in content survive app updates more cleanly than a brittle absolute file path would.

Uploaded media uses local file paths

User-added media works differently.

When you upload a file, Atmos stores the real local path for that item. That means uploaded content is tied to the file the user selected from disk, not to a bundled app resource.

This is why uploaded items behave more like personal library assets while built-in content behaves more like app-owned defaults.

Built-in items are protected from deletion

Atmos explicitly treats built-in content as non-deletable.

In the library editing flow, built-in profiles do not expose the normal delete option. When profile removal happens in the underlying player logic, the app also guards against deleting built-in content.

This protects the default library from being permanently dismantled by ordinary user actions.

Hidden behavior: reset removes user content but rebuilds built-ins

A full app reset does not flatten everything equally.

When Atmos resets user content, it clears user-added profiles and then re-seeds the built-in library.

That means built-ins are treated as the base layer of the app, while uploads are treated as custom additions on top of that base.

Media type is what defines the basic role of a profile

Every Atmos profile has a mediaType.

That type can be:

• audio
• video
• image

This is the first part of how the app decides what a profile can do.

For example:

• image profiles are visual-only
• audio profiles are playback-only
• video profiles can act in more than one role depending on their configuration

Video mode adds a second layer of meaning

Video profiles are more flexible than plain audio or image entries.

Each video profile also has a videoMode, which determines whether the file contributes:

• audio only
• background only
• both audio and background

This is one of the most important hidden content rules in the app because it means one uploaded video file can behave differently depending on how the user configures it.

Hidden behavior: a single video can belong to both library categories

Atmos does not force video content into only one section of the library model.

Because profile contribution is derived from mediaType plus videoMode, a video profile can appear as both:

• an audio-capable item
• a background-capable item

This is why video content can feel more integrated than a simple “video wallpaper” add-on feature.

Atmos derives contributesAudio and contributesBackground

The app does not rely only on the raw file extension once a profile exists.

Instead, it derives whether a profile contributes audio or background functionality based on its stored metadata.

That is how Atmos decides which profiles belong in different library views and which profiles qualify for actions like:

• playback loading
• background selection
• upload ordering flows

This derived-role model is one of the reasons the library can stay flexible without becoming messy.

Uploaded files are classified by extension first

During upload, Atmos determines the raw file type from the file extension.

Broadly speaking, it separates:

• audio formats
• video formats
• image formats

If a file type is unsupported, the app warns the user instead of pretending the upload succeeded.

So extension-based classification is the first gate before the richer profile model is created.

Hidden behavior: uploads can branch into multiple edit steps

Atmos does not always move every upload through the exact same linear path.

After files are selected, the upload flow can add extra edit steps depending on what the chosen set contains.

For example:

• if multiple background-capable items exist, Atmos can show a background ordering step
• if multiple audio-capable items exist, Atmos can show an audio ordering step

This means the upload flow adapts to the content mix instead of forcing every user through unnecessary screens.

First uploaded items can become active automatically

When the upload flow finishes, Atmos does more than simply append the new profiles to the library.

It also looks for:

• the first newly added audio-capable item
• the first newly added background-capable item

If it finds them, the app can immediately load the audio profile and set the background profile active.

That gives uploads a more satisfying “I added it and now I can use it” feel.

Hidden behavior: image uploads do not become audio by accident

Atmos is careful here.

If a new item contributes only background functionality, it can become the active background, but it does not accidentally get treated like an audio source.

Likewise, an audio-only item does not become a background just because it was uploaded in the same batch.

The contribution rules are strict enough to keep roles clean.

File resolution works differently for built-ins and uploads

Whenever Atmos needs the actual file path to load or apply something, it resolves the stored path.

For built-ins:

• the bundle: path is converted into a real resource path inside the app bundle

For uploads:

• the stored local file path is used directly

This unified resolution step is what lets the rest of the app operate on both content types without needing separate playback and wallpaper code for each.

Missing uploaded files can break continuity in ways built-ins usually do not

Because uploaded items depend on real user file paths, they are more vulnerable to file movement or deletion outside the app.

If the original file no longer exists where Atmos expects it, the app cannot load it.

Built-ins are usually more stable in this respect because they are shipped inside the app bundle and resolved from the bundle reference.

That is one of the practical differences between app-owned content and user-owned content.

Built-in content also participates in export and import differently

When Atmos exports a profile package, uploaded files can be copied into the export bundle so they travel with the setup.

Built-in content works differently. Because built-ins are already part of the app, Atmos can preserve their bundle-style references instead of repackaging them the same way as user media.

This is another place where the two content sources are handled differently for good reason.

Hidden behavior: duplicate naming is handled at upload time

Atmos also protects the library from simple naming collisions.

When you upload new content, the app can generate a unique profile name if the desired name already exists.

That helps avoid a confusing pile of identical titles when users add multiple similar files.

Why the library feels more unified than it really is

One of the clever parts of the system is that Atmos makes built-in and uploaded content feel like one cohesive library even though the underlying rules are different.

Under the surface, the app is balancing:

• protected bundle-owned defaults
• user-owned local files
• role derivation from media type
• special behavior for videos
• restore and export rules
• deletion safeguards

That is why the library can feel simple on the front end while still supporting a lot of different content behavior.

What users should take away

The practical rules are:

• built-in content ships with the app and is re-seeded automatically
• uploaded content uses local file paths and belongs to the user’s library
• built-ins are protected from ordinary deletion
• profile behavior is determined by media type and, for videos, video mode
• one video can contribute to audio, backgrounds, or both
• uploaded content can become active automatically right after import

Once you understand those rules, the library makes a lot more sense.

Atmos is not mixing everything together carelessly. It is using one shared profile model with different source rules underneath.