Motion Desktop

Motion Desktop manual

Browse the instructions below or search for a feature. Need a hand? Contact Koingo Support.

11 articles

About Motion Desktop and first launch

Getting Started

Motion Desktop displays pictures and videos beneath your desktop icons. Use its menu bar icon to open Playback Queue, start or stop the desktop, pause or resume, and open Settings.

  1. Open Playback Queue and use the toolbar Add menu to choose files, folders, Apple Photos, Media Archive, or a Smart Folder.
  2. Select an item to review its preview and playback options. Enable the items you want to include.
  3. Press Start to begin desktop playback. Pause holds the current playback; Stop ends desktop playback. Use Next Item after Pause in the toolbar, or in the menu bar menu, to advance to another picture or video. Next Item is available while playback is running and unpaused with at least two enabled media items.

New installations begin with an empty queue. There is no bundled starter playlist or command to restore one.

Settings are grouped into General, Playback, Appearance, Captions, Audio, and Downloads. Updates and Debug appear when available.

Adding and organizing media

Getting Started · Playback

Playback Queue has separate Pictures & Videos and Background Music tabs. The toolbar Add button and the plus button beneath the current list open the same Add menu for that tab.

In Pictures & Videos, choose Files, Folder, Apple Photos, or Media Archive to add media, or choose New Queue Folder or New Smart Folder. In Background Music, choose Files or Folder to add music, or choose New Music Folder or New Smart Folder. The new ordinary folder commands organize existing entries; a Smart Folder follows its source and search rules.

Use Add for new media, sources, and organizing folders. The cog provides actions for existing entries, such as moving or sorting, with folder renaming where offered. It is disabled when there are no applicable actions.

Drag items to reorder them or place them inside folders. Enable or disable individual items and folders to control what participates in playback. A disabled parent folder also excludes its contents.

Select a picture or video to see its preview and change its timing, motion, or border setting. Per-item choices apply to that queue entry. Defaults for New Media in Settings > Playback apply to items added later.

Saved queues keep separate contents and playback progress. Switching queues preserves each queue's saved position when Resume saved playback progress is enabled. Duplicating a queue copies its contents and starts fresh playback history.

Browsing and adding Apple Photos

Getting Started · Apple Photos

Open Apple Photos from Playback Queue to browse your accessible albums. Motion Desktop reads your Photos library without changing its originals. If access is unavailable, use the explanation and access button shown in the browser; full album browsing requires full Photos access.

Drag the divider between the albums and media to adjust the sidebar. Motion Desktop remembers its width. The album count sits beneath the sidebar, while the media count is right-aligned beneath the media grid. When items are selected, that count shows the selected and displayed totals. Search and media-type filters apply to the current album, and the count describes the items currently shown.

Choose All, Videos, or Photos to filter by media type, and use the search field to find names within the album. Press Escape in a nonempty search field to clear the search. Background loading is indicated separately from the media count, and empty, unavailable, and no-match states explain what to do next.

Drag selected media into Playback Queue, choose Add Selected to Queue from its contextual menu, press Return with the grid focused, or double-click a media item. To add a live album, use its contextual Add Album to Queue command, double-click the album, press Return with the album selected, or drag the album to the queue. Adding an album includes the album itself; the current search and media-type filter only affect browsing.

Live Photos albums update as their library contents change. Pending imports capture the target queue and Photos identities, so switching queues does not add the selection to a different queue. Removing an album or a Photos item from Motion Desktop does not delete its original from Apple Photos.

Desktop captions, dates, and fonts

Captions

Open Settings > Captions and enable Show media captions on the desktop.

  • Caption content: choose Name, Creation Date, or Name and Creation Date.
  • Date format: choose the example showing your preferred date appearance. The menu previews the current date using the standard short, medium, long, and full system formats, plus the SQL date and time format, such as 2026-10-22 10:14:41. The standard formats follow your macOS language and region settings. SQL date and time uses a four-digit year, two-digit month and day, and a 24-hour time including seconds. All choices use your Mac's time zone.
  • Caption position: choose a top or bottom corner, or a centred position.
  • Caption font: open the macOS Fonts panel to choose the family, typeface, and size.
  • Text colour and Background colour: choose a preset or a recent selection using the popup. Select Custom Color… to open the macOS colour picker, or select it again to edit the current custom colour.
  • Background opacity: choose a solid plate or reduce opacity, including zero for no visible plate.

The colour menus include up to ten recent colours with friendly names. Custom Color remains selected while its picker is open; closing without choosing a colour restores the previous choice. Hold the pointer over a custom colour popup to see its name and hexadecimal value.

For ordinary local files, Creation Date is the file system's creation date, not an embedded camera capture date. For Apple Photos items, it is the asset's creation date supplied by Photos. The Media Archive currently does not provide creation dates.

If a trustworthy creation date is unavailable, the caption falls back to the item's name, including when Creation Date is selected. Download time, cache-file creation time, and modification time are not substituted.

Local names follow the source filename; Media Archive names come from the catalog. Caption appearance and placement changes apply to the desktop without restarting playback.

Display sizing, transitions, and border colours

Appearance

Open Settings > Appearance to choose the target display, media sizing, border treatment, and transitions.

  • Crop to fill screen: fill the display while cropping edges as necessary.
  • Scale to fit: keep the whole picture or video visible without changing its proportions. Unfilled areas use the border colour.
  • Stretch to fill screen: fill the display by changing the media's proportions.

Pan and zoom can still enlarge and crop a picture. Turn it off when you want the whole picture to remain visible throughout its display interval.

The global border popup offers Black, Match Media, and Custom Color…. Black and Custom Color show round colour previews. Match Media has an eyedropper icon and samples an available thumbnail, using a fallback while that image is unavailable.

Select Custom Color… to open the macOS colour picker, including when Custom Color is already selected. The picker starts with the stored custom colour, and Custom Color stays selected while it is open. Choosing a colour applies it live. Closing the picker without choosing a colour restores the previous menu choice.

The menu includes up to ten recent colours with friendly names such as Banana Yellow and Forest Green. Other shades receive approximate names such as Pinkish; numbered names such as Pinkish #2 distinguish similar choices. A custom colour's name and exact hexadecimal value appear in the popup's help tag when you hold the pointer over it.

In the selected picture or video's queue inspector, the Border popup adds Default. Default inherits Settings > Appearance. Choose Black, Match Media, or Custom Color there to give that item its own setting. No override checkbox is needed.

Border colour changes update playback and previews without restarting the item. Set Transition to zero for direct changes, or increase it for a crossfade. Short media can use a shorter overlap.

Media Archive, downloads, and offline playback

Downloads

Open Media Archive from the queue's Add menu or the menu bar. Browse collections, preview media, and add the items you want to a queue. Download indicators show each item's progress and cached state.

Settings > Downloads controls online-video delivery, preferred media quality, maximum storage, and the amount of disk space to keep free. Cached media plays first. Pictures download before playback; online videos can stream or download before playback according to your setting.

Use Keep Offline for archive media you want protected from automatic cache cleanup. Existing cached content can remain browsable when the server is unavailable, but an uncached item still needs a working connection.

Automatic cleanup removes eligible older downloads when the configured capacity or disk-space policies require it. Current and upcoming media, active downloads, and Keep Offline items are protected. Clear Downloads also keeps protected items; it does not delete queue entries or your originals.

If protected content prevents enough space from being freed, review Keep Offline choices or free disk space. Changing quality does not upscale the source, and an available lower-quality or kept copy may be used when the preferred copy is unavailable.

Play Once, loops, and picture duration

Playback

Play once controls one visit to an item. It does not permanently tick the item off, disable it, or stop the entire queue after one pass. When the queue finishes, playback begins another cycle.

  • Play once: a video plays from start to finish. A picture remains for its selected Picture duration.
  • Number of loops: repeat the item for the selected count. Each picture loop uses its selected Picture duration.
  • Loop for a duration: repeat the item for the selected total time. Videos retain their playback speed rather than slowing down to fill that duration.

Change an individual picture or video's timing by selecting it in Playback Queue. Defaults for New Media in Settings > Playback set the initial options for items added later. Moving a Settings slider does not replace options already saved with existing media.

To update media already in the current queue, choose the defaults in Settings > Playback and click Apply to Existing Media… below the Defaults for New Media group. Review the item count and confirm Apply. This replaces playback timing for all pictures and videos in the current queue, including disabled items and items inside folders. It also applies the Pan and zoom checkbox to pictures while preserving their stored motion paths.

Border colours, other saved queues, background music, and video sound and speed settings are unchanged. A picture keeps its elapsed display time when timing changes; a playing video may restart to apply its new options.

For a thirty-second slideshow, choose Play once, set Picture Duration to thirty seconds, and use Apply to Existing Media… for media already in the queue. No app restart is required.

Loop for a duration uses the selected total duration instead of Picture Duration, so Picture Duration is disabled in that mode. For Number of loops, each picture loop uses Picture Duration and the total display time is multiplied by the loop count.

Picture motion offers Gentle Pan & Zoom, Random Zoom & Pan, and a Custom Start and Finish path. Choose the playback speed in Settings > Playback and the transition between items in Settings > Appearance.

Shuffle and saved playback progress

Playback

Open Settings > Playback to choose the queue order:

  • Shuffle albums: shuffle folder order while retaining the media order inside each folder.
  • Shuffle within albums: retain folder order and shuffle the media within each album.
  • Shuffle all media: mix eligible media across folders.

Shuffle tracks items that have actually appeared on the desktop. Preparing or downloading a future item does not mark it as played. Eligible items become available again after the cycle finishes. Changing the shuffle mode starts a fresh cycle.

Enable Resume saved playback progress to continue each saved queue after Stop, a queue switch, or relaunch. Motion Desktop saves the current item, its supported playback position or remaining interval, and the current shuffle cycle.

The last visible picture or video may appear again because its remaining playback is being resumed. This does not mean the queue has restarted at its first item. Missing, disabled, or changed media can require a new playback position.

The Restart Queue Cycle button is below the resume explanation in Settings > Playback. Choose it to clear the current queue's saved progress and shuffle history. Its media and per-item settings stay in the queue. A running queue begins the new cycle immediately; a stopped queue begins it the next time you press Start.

Startup playback is a separate choice in Settings > General. Turning off Resume saved playback progress makes a new Start use a fresh run rather than the saved checkpoint.

Smart Folders and file access

Smart Folders

A Motion Desktop Smart Folder uses a source folder and search rules to keep matching media in its queue folder. Choose Match All or Match Any for the rules. With no rules, all supported media beneath the source folder is included.

The app-created editor currently uses one source folder and its descendants. To include several sibling folders, choose their common parent and suitable rules, or create separate Smart Folders. This is separate from the search locations stored in a Finder Smart Folder.

A Smart Folder created inside Motion Desktop is saved with its queue in the app's preferences. Creating one does not write a standalone .savedSearch file to a folder on disk. Motion Desktop does not provide a whole-preferences sync workflow between Macs; queue contents, playback progress, and macOS file-access bookmarks are part of each Mac's local setup.

You can also add a Finder Smart Folder (.savedSearch). A Finder search may refer to more than one location. When Motion Desktop requests Media Access, select the folders containing the matching files. Granting access allows those results to be opened; it does not expand or rewrite Finder's saved query.

To reuse a Finder search on another Mac, you can keep its .savedSearch file in a synced folder and add that file to Motion Desktop separately on each Mac. Its search locations must resolve on that Mac, the original media must be available, and Motion Desktop needs the appropriate local access grants on each Mac. Copying or syncing the search file does not supply those grants or rewrite its search locations.

Access to the .savedSearch file alone does not necessarily grant access to its results. If a source is unavailable, reconnect its drive or grant access through the folder's Media Access controls. Incomplete or unsuccessful searches retain existing queue members rather than treating the source as an empty folder.

When Motion Desktop scans a source folder, it skips packages, aliases, and symbolic links. Select the original media locations rather than relying on aliases or links to other folders.

Use the original files or search definition to change generated members. Motion Desktop preserves retained members' playback options as live sources update. Ordinary folder import and a live Smart Folder are different: use the Smart Folder when you want membership to follow later changes.

Startup, unavailable media, and support

General · Troubleshooting

Settings > General separates three startup choices: open Motion Desktop at login, show Playback Queue on launch, and start desktop playback on launch. Resume saved playback progress is controlled separately in Settings > Playback. Pause playback on battery power is in General under Energy.

If nothing appears, confirm that desktop playback is started, the current queue has enabled media, playback is not paused, and Settings > Appearance targets a connected display. A new installation has an empty queue until you add media.

For unavailable local files, reconnect the source drive or use Locate File where offered. For cloud-provider files, ensure they are available locally and the provider has finished downloading them. For online media, check your connection and Downloads settings, or use a previously cached copy.

Motion Desktop skips media that cannot be played during that attempt and stops cleanly if nothing is available. Choose an item and press Play to try it again after correcting the problem.

Each saved queue supports up to 5,000 picture/video entries and 5,000 music entries, including folders. Across saved queues, the combined limit is 20,000 entries and 50 saved queues. Split a larger collection into suitable queues or source groups.

Installing a macOS update: after a successful download, the updater shows a separate installation page. Downloading does not replace the application or reopen it automatically.

  1. Find the download: use Show in Finder to locate the completed download. You do not need to download it again.
  2. Open the disk image: click Open Disk Image and leave the mounted image open in Finder.
  3. Quit Motion Desktop: use the Quit button when you are ready to replace the app.
  4. Replace the installed app: drag the new Motion Desktop app from the disk image into the folder containing your existing copy and approve replacing it. Show Current App identifies the installed copy before you quit. If you keep the app in an Applications subfolder, replace it there. Then open the installed copy, rather than the copy in the disk image.

Back to Release Notes returns to the version information. Installation Steps… returns to the installation page without downloading again. The download remains available after Motion Desktop quits. Opening the download and quitting are separate actions; neither happens automatically.

For assistance, use Help and Support from the menu bar. Include the Motion Desktop version, macOS version, what you expected, what happened, and relevant entries from the standard Debug Log.

Video sound and background music

Audio

Open Settings > Audio to control video sound and background music separately. Mute video sound affects audio embedded in videos; it does not replace the background music controls.

Add music using the Background Music tab in Playback Queue. Organize tracks into folders and use each visual album folder's inspector to select its background music association. Compact music rows use a local file's Finder icon when available; online tracks use generic icons.

Enable Follow the current album's background music to switch to the associated music folder as the desktop enters an album. Albums without a matching folder leave the current music selection unchanged. Adjust Fade between tracks to control music handoffs.

In Settings > General, Remove linked music with online albums is enabled initially. When you remove an online album, Motion Desktop also offers to remove its associated music folder from that queue. Music still associated with other retained media is kept. Turn the setting off to keep linked music when removing albums. Removing music never removes the source visual album, and this operation does not delete original files or downloaded media.

Desktop pause and stop also pause or stop associated background playback. Review the independent background music enable and mute controls when troubleshooting silent music.