Raytonica Help

1. Overview

Raytonica is a feature-rich media player for macOS. With a tag and filter-based organization system, Raytonica helps you quickly discover and organize files across large libraries.

• Supported OS: macOS 26 (Tahoe) or later on a Mac with Apple silicon (Intel-based Macs are not supported)
• Supported media: Video / Audio / Images (see “Supported Formats”)
• Playback engine: mpv (libmpv)
• Languages: English / Japanese / German / French / Spanish / Korean (follows the system language; can be changed in Settings)

2. Getting Started — Registering Library Folders

1. Click the sidebar button at the left end of the toolbar (next to the window buttons), or press B to open the Library Browser.
2. Use the + button in the sidebar’s Folders heading, or drag folders from Finder onto the Library Browser (or the player window). For a single folder you’re asked whether to also register its subfolders as folders (either way, videos inside subfolders are added to the library; choosing Register with Subfolders also registers each subfolder as its own folder, so you can find and pick it directly — if unsure, This Folder Only is fine). When you drop several folders at once, the ones not yet registered are added together.
3. Media files inside the folder are scanned automatically and added to the library.
4. Subfolders are scanned recursively.
5. When the scan of your first folder finishes, a Getting Started card appears over the player once (double-click a video in the library to play it, N / P for the next / previous file, 1–9 to add or remove a tag, T to choose or create a tag, B for the library; the keys shown follow your assignments in Settings > Shortcuts). After you close it with Get Started, it doesn’t appear again. You can show it any time with Show Tips in the Help menu. In Lite, if you haven’t started the Pro trial yet, the card also shows “Try the Pro features (range tags, visual search and more) free for 14 days” with a Try Pro button (clicking it starts the trial, shows “Pro trial started (14 days left)”, and removes the line).

If you have not registered any folder yet, you can also use the Add Folder… button shown in the player area.

Files opened during a scan: A file you open during a scan (with Open File…, by dropping it, or from Finder) opens when the scan finishes. A message tells you it’s waiting (if you open several, the last one opens).

About network folders (NAS): Network folders are supported. Tag data is preserved while the folder is offline (the icon turns orange). When the mount path stays the same, Raytonica re-scans automatically as soon as the folder is reachable again. When the mount path changes (for example SMB remounts with a /Volumes/X-2 suffix), right-click the offline folder and choose “Reconnect…” to point it at the new path.

About folder access permission: When you register a folder inside Documents, Desktop, or Downloads, or on an external drive or network drive (NAS), macOS asks for permission the first time the folder is read. Choose Allow. If you choose Don’t Allow, the videos in that folder won’t appear in the list. To allow access later, open System Settings > Privacy & Security > Files & Folders and turn on the matching item under Raytonica.

3. Supported Formats

For security reasons, formats that reference content outside the file itself (MKV ordered chapters, MOV reference movies, playlist files, and media inside archives) are not supported. Automatic loading of subtitle files with the same name as the video continues to work as before.

HDR videos

HDR videos (HDR10 and HLG) are shown at HDR brightness on displays that support HDR (the Liquid Retina XDR display on MacBook Pro, or an external display with HDR turned on in System Settings). On other displays they’re converted to standard brightness (SDR). Moving the window to another display switches automatically. The Mini Player works the same way.

• The Picture in Picture window shows HDR videos at standard brightness (SDR).
• Dolby Vision Profile 5 videos aren’t shown with correct colors. Profile 7 and 8 videos are shown as HDR10 / HLG.

4. Keyboard Shortcuts

Fixed shortcuts (not customizable)

Customizable shortcuts (default values)

You can change these in Settings > Shortcuts (click a key, then press the new key; keys with Shift can be assigned too). You can also open it with Keyboard Shortcuts in the Help menu.

5. Playback

Basics

• Opening a file directly: Besides ⌘O and dragging onto the player window, you can open files from Finder with Open With. Files outside your registered folders follow the “file open behavior” setting.
• Open URL (Pro): Choose File > Open URL… (⌘⇧O) to play an http or https URL, including HLS streams. A URL on the clipboard is filled in for you, and the 10 most recent URLs are listed below. URLs are not added to the library, and tagging isn’t available. If a URL can’t be opened, “Couldn’t open” appears on screen.
  • Resume: The playback position is remembered for each URL you open, and opening the same URL again resumes where you left off (as with local files, playback starts from the beginning if 5 seconds or less remain). The recent URL list shows where each one will resume, such as “Resume at 12:34”. Live streams and other URLs that can’t be seeked aren’t remembered. Up to 200 URLs are remembered; the ones you haven’t opened for the longest are removed first. Videos from a media server (Jellyfin / Emby) use the position stored on the server.
  • Save URL: Keep URLs you watch often in the sidebar as Saved URLs (see “Saved URLs” below). Click the bookmark button at the right of a recent URL (or right-click it and choose Save URL), or choose File > Save Current URL while it’s playing.
  • Video site page URLs: Raytonica doesn’t include yt-dlp. Only if you have installed yt-dlp yourself (in /opt/homebrew/bin, /usr/local/bin or ~/.local/bin), a page URL that isn’t a video file or an HLS stream is converted to a playable URL with yt-dlp before opening (up to 30 seconds). The playback position is remembered under the page URL you entered. The page title is shown on screen and in the playback history. Which sites work depends on yt-dlp and on the site. Please follow each site’s terms of use.
• Full-screen toggle: Double-click the video or image area to switch between full-screen and normal view. Double-clicking on the seek bar, buttons or the toolbar does not trigger it (for audio files, clicking the waveform toggles immersive mode instead).
• Double-click to play from the library: Double-clicking a file in the library plays it in full screen (if you are already in full screen, it stays that way). Playing with the Return key does not change the window state.
• Playback order: Switch between Normal / Repeat all / Shuffle from the toolbar or with the S key. In Normal, playback stops after the last file. After it stops, Space or the play button plays it again from the start, and the arrow keys or the seek bar take you back to a point to play from.
• What’s playing: While a filter, folder scope, playlist, or tag (when you play from a tag in the Library) is active, a chip (icon + name + current position / total) is always shown in the center of the toolbar, to the right of the file name. Click the chip to open Playing in the inspector; click its ✕ to clear it. In shuffle mode only the total is shown.
• Inspector: The inspector button on the right of the toolbar (or H) opens a panel to the right of the player with Tags, Segments, Playing, History and Info tabs. Segments lists the range tags and scenes of the current file (see Range tags and Scene detection below). You can keep it open while you watch and tag. In Playing you switch between filters, playlists and folders, and see or clear what is currently playing. History lists played files newest first, each with the time it was played (only the time for today).
• F / T / Y keys: Pressing one starts selection mode, where 1–9 (and 0 to clear a filter) or ↑ ↓ + Enter choose an item. Choosing an item, Esc or the same key ends selection mode. If the inspector is open it switches to the matching tab; if it is closed, the same content appears temporarily below the inspector button. Outside selection mode, 1–9 always tag the playing file, whichever tab the inspector shows.
• Sort order (Normal mode): Choose Name ascending / Name descending / Creation date ascending / Creation date descending in Settings. Name order sorts by the path including folders (folder order, then file name within each folder).
• Playback order while a filter is applied (Normal mode): Files play in the order shown in the filter result table. Click a column header (Name / Path / Kind / Size / Created / Modified / Last Played) to sort, and that order becomes the playback order and is kept for next time (shared by all filters). If no column is chosen, the sort order from Settings is used and the table is shown in that order. Choosing a sort order again in Settings clears the column you chose in the table.
• Shuffle mode: Random playback that excludes recent history to prevent duplicates.
• Resume position: Playback position is remembered across app launches. When you reopen the same file, Raytonica resumes from where you left off (if the remaining time is 5 seconds or less, playback starts from the beginning). To switch files quickly, it resumes from a moment (a few seconds at most) before that position.
• Seek bar thumbnails: When you hover over the seek bar (or drag it), a thumbnail of the video at that position appears above the time. Thumbnails are shown for videos on your Mac and on a NAS; for audio, images, URL playback, and videos on a disconnected drive, only the time is shown. The first time you point at a position, the thumbnail may take a moment to appear (especially on a NAS).
• Toolbar and seek bar auto-hide: The toolbar and seek bar hide automatically after the cursor stays still for 2 seconds, and reappear when you move the cursor. While hidden, clicking where the toolbar would be does not activate any button; it only reveals the toolbar (click again once it is visible). Clicking where the hidden seek bar would be does not seek either; it is treated as a click on the video or waveform behind it (nothing happens for video and images; for audio files it counts as a waveform click and toggles immersive mode).

Select Text in a Paused Video (Live Text)

When you pause a video, you can select and copy text that appears in the picture (subtitles, signs, slides and so on). This uses macOS Live Text.

• Shortly after you pause, the Live Text button appears at the bottom right of the picture. Click it to highlight the text that was found
• Double-click or drag to select text, then press ⌘C to copy it. You can also translate or look it up
• Elsewhere on the picture, double-click still toggles full screen and right-click still shows the menu
• Not available while zoomed, flipped, filled to the screen, in Picture in Picture or while playing with AirPlay. You can turn it off in Settings > Playback

A-B Loop

Press L to cycle through three states:

1. Set point A (loop start)
2. Set point B (loop end — the A→B region repeats)
3. Clear loop

The loop region is shown in orange on the seek bar.

Chapters

For videos with chapters (MKV, MP4 and others), you can move between chapters.

• Chapter boundaries are marked on the seek bar. When you hover over the seek bar, the chapter name appears next to the time
• Press ] to go to the next chapter and [ to go to the start of the previous one (you can change the keys in Settings > Shortcuts). If you’re more than 2 seconds into a chapter, [ goes back to the start of the current chapter; within 2 seconds, it goes to the previous chapter. The chapter name appears at the bottom of the screen when you move
• You can also use Previous Chapter / Next Chapter in the Playback menu, or pick a chapter from Chapters in the “…” menu at the right end of the toolbar
• Chapters without a name are shown with a number, such as “Chapter 1”

Skip Opening & Ending (Pro)

You can skip the opening and ending of episodes.

• While the opening or ending plays, Skip Opening / Skip Ending appears at the bottom right of the screen. Click it to jump to the end of that part (if the ending runs to the end of the video, Raytonica moves on to the next file)
• In Settings > Playback > Opening & Ending, choose Show Skip Button (the default), Skip Automatically or Do Nothing. When a part is skipped automatically, “Skipped the opening” appears at the bottom of the screen. If you go back into a part that was skipped, it isn’t skipped again
• Parts are found in this order (for each kind, the first source that has one is used)
  1. Range tags: range tags named OP or ED (Opening, Ending and the Japanese names also work), so you can mark the parts yourself
  2. Jellyfin segments: when playing from a Jellyfin 10.10 or later server, segments made by the server (for example, with the Intro Skipper plugin)
  3. Chapter names: chapters named Opening, OP, Intro, Ending, ED, Credits and so on (common in MKV files). The part runs from the start of that chapter to the start of the next one
• In Lite, the button shows PRO, and clicking it shows what Pro offers

Filmstrip

Press W or use the … menu at the right end of the toolbar to show the filmstrip below the player. The current playback queue is displayed as horizontally arranged thumbnails — click one to switch instantly. While the cursor is over the filmstrip, you can also use ←/→ to move between adjacent files.

Audio waveform and immersive mode

When you play an audio file (mp3 / flac / wav / m4a / aac / ogg, etc.), a full-length amplitude waveform is shown in the player area in place of video. The waveform fills with color up to the current playback position, so you can grasp a track’s structure (quiet sections and peaks) at a glance. It is generated in the background by AVAssetReader, so the UI stays responsive even for long files.

• Seeking is done with the seek bar (playback position bar) at the bottom of the screen.
• Clicking the waveform toggles immersive (full-screen) mode, filling the screen with the waveform. Click again or press Esc to exit.

Media Keys and Now Playing

You can control Raytonica with the media keys on your keyboard (▶︎⏸, ⏭, ⏮), the buttons on AirPods or headphones, and Now Playing in Control Center or the menu bar.

• Play/Pause works like Space, Next like N, and Previous like P (following the current playback target or playlist order)
• Now Playing shows the file name, folder name, duration, and a thumbnail (embedded cover art for audio files). You can change the playback position with the Now Playing seek bar
• This also works in the Mini Player, Picture in Picture, and while playing over AirPlay
• Images aren’t shown in Now Playing
• If another app (such as Music) is also playing, the app that started playing most recently receives the keys (this is how macOS works)

Keep on Top

Choose Keep on Top in the View menu (⌃⌘T) or in the … menu at the right end of the toolbar to keep the main window in front of other apps’ windows — handy for watching while you work in another app.

• Choose it again to turn it off. The setting is kept the next time you open Raytonica
• The library panel, the Settings window and the Mini Player still appear in front of the main window
• It has no effect in full screen (the window stays on top again after you leave full screen)

Mini Player

Choose Mini Player from the … menu at the right end of the toolbar, or press Shift+M, to detach the currently playing media into a small always-on-top floating window — handy for keeping an eye on a video while working in another app.

• Press Shift+M again, or use “Back to Main Window” in the Mini Player, to return to the main window.
• While the Mini Player is shown, the main window’s keyboard shortcuts (panel toggles, etc.) are disabled.
• Pressing Shift+M while in full screen first exits full screen and then switches to the Mini Player (the … menu item is disabled while in full screen). Closing the Mini Player returns to the main window at its normal size.

The Mini Player can only be launched while a file is playing.

Picture in Picture (Pro)

Choose Picture in Picture from the Video menu (⌥⌘P) or from the … menu at the right end of the toolbar to play in macOS’s built-in Picture in Picture (PiP). The PiP window also stays above full-screen apps and other Spaces.

• Use the buttons in the PiP window to play / pause, skip back or forward, or return to Raytonica. You can resize the window freely. It snaps to the corners of the screen, but you can hold ⌘ while dragging to place it anywhere.
• While PiP is on, the video area of the main window turns black and shows “Playing in Picture in Picture”. Controls in the main window (next file, seeking, tagging, and so on) keep working.
• PiP keeps going when you move on to the next video. It ends when you move on to an image or audio file.
• Choose the same menu item again (Exit Picture in Picture) or close the PiP window to end it.
• Available only while a video is playing. Not available during AirPlay or in the Mini Player (opening the Mini Player ends PiP).
• Horizontal and vertical flips aren’t applied in the PiP window. HDR videos are shown at standard brightness (SDR).

How it differs from the Mini Player: PiP is macOS’s small built-in window with minimal controls. The Mini Player is Raytonica’s own window, with previous / next file, seeking, and the audio waveform.

Rotation

Use Rotate Right 90° (⌘R) and Rotate Left 90° (⌘L) in the Video menu to turn the video in 90° steps — for example, when a vertical video shot on a phone was saved sideways.

• The current angle (0° / 90° / 180° / 270°) appears at the bottom of the screen
• It returns to 0° when you open another file (it isn’t remembered per file)
• Aspect ratio and zoom work on the rotated picture
• Available only while playing a video (not for images or audio)

Zoom, Pan and Aspect Ratio (Pro)

• Zoom: Pinch on the trackpad over a video or image to zoom in or out around your fingers (100%–800%).
• Pan: While zoomed in, drag the picture to move around. It stops at the edges of the picture.
• Aspect ratio: Right-click the player, or choose Video > Aspect Ratio in the menu bar, to pick Original, Fill Screen (zooms until the black bars disappear), Remove Black Bars, or 16:9 / 4:3 / 2.39:1 / 1:1 / 9:16. Choosing a ratio crops the center of the video to that ratio (videos only).
  • Remove Black Bars: Raytonica checks several points in the video and trims the black bars burned into the top, bottom or sides (this takes a few seconds). If the bars change between scenes, it trims only as far as no scene gets cut off, so some scenes may keep a bit of black. If there are no black bars, “No black bars found” appears and the ratio goes back to Original. Available for local and NAS files (not for videos played from a URL).
• Reset: While zoomed in, the zoom level (e.g. “150%”) and an ✕ appear in the top-right corner. Click ✕, or choose Reset Zoom from the right-click menu or the menu bar, to return to the original size.
• Switching to another file resets zoom, pan and aspect ratio.
• Scrolling (seek / volume) and double-clicking (full screen) work as before. Pinch and drag are not available in the Mini Player.
• Images are loaded at screen resolution, so they may look soft when zoomed in a lot.

Pro feature: Zoom, pan and aspect ratio require Raytonica Pro. In Lite, pinching or choosing Aspect Ratio — PRO from a menu shows what Pro offers (see “15. License”).

AirPlay

There are three ways to watch or listen on an Apple TV or an AirPlay-compatible TV or speaker.

Audio only on an AirPlay speaker (Lite / Pro)

In Control Center, open Sound (or click the volume in the menu bar) and choose an AirPlay speaker (HomePod, an AirPlay-compatible TV, etc.) as the output. The picture stays on your Mac and only the sound goes to the speaker. You can switch while a file is playing. Color LUTs, the equalizer, subtitles and everything else keep working. AirPlay delivers audio about 2 seconds late, so on some devices picture and sound may drift apart.

Screen Mirroring / extended display (Lite / Pro)

In Control Center, choose Screen Mirroring and pick an Apple TV or AirPlay-compatible TV to show your Mac’s screen on the TV. To fill the TV with the video, use it as an extended display, move the player window to the TV and enter full screen. Every Raytonica feature — color LUTs, the equalizer, subtitles, zoom and so on — shows up as is. Because the screen is compressed before it is sent, picture quality and delay are worse than with Play with AirPlay below, and HDR isn’t sent. Works with any file format.

Play with AirPlay (Pro)

Sends the video or audio itself to the AirPlay device and plays it there. The picture is sharper than with Screen Mirroring, and your Mac’s screen stays free for other work.

• Starting: When an AirPlay device is found, an AirPlay button appears on the right side of the toolbar. Click it and choose a device: playback on the Mac stops and continues on the AirPlay device from the same position. You can also choose Play with AirPlay… from the … menu at the right end of the toolbar (if no device is found, “No AirPlay devices found” appears).
• What can be sent: MP4 / MOV / M4V and similar videos, MP3 / M4A / AAC / WAV / AIFF / FLAC and similar audio, URLs opened with Open URL (including HLS), and videos on a media server (Jellyfin / Emby).
• What can’t be sent: MKV / WebM / AVI / WMV / OGG / Opus and similar formats (the button is disabled, and its tooltip suggests Screen Mirroring). Even an MP4 may fail depending on the codecs inside; in that case “Couldn’t play this with AirPlay” appears and playback continues on the Mac. Images can’t be sent.
• Media server videos: Raytonica sends an HLS stream converted by the server, so even MKV and similar files can be sent (the server does the conversion work). The TV connects to the server directly, so this doesn’t work if the server URL is localhost or 127.0.0.1; connect to the server with its address on your home network instead.
• Controls while using AirPlay: The player area shows “Playing with AirPlay” with play / pause and Return to Playback on Mac buttons. Space, ← → (seek), the seek bar and the play button in the toolbar control the AirPlay device. Adjust the volume on the TV or other AirPlay device. Frame stepping (J K), A-B loop and playback speed changes don’t work while using AirPlay.
• Subtitles: The text subtitle you’ve selected on the Mac is shown on the AirPlay device too (for MP4 / MOV / M4V files and media server items).
  • Subtitles inside the video: Sent as they are. The subtitle delay isn’t applied on the AirPlay device.
  • Subtitle files (SRT / VTT / ASS, including ones downloaded with online subtitle search): The subtitle delay is carried over. This works only for videos on this Mac’s startup disk; for videos on external disks or a NAS, the video is sent without subtitles and a message tells you so. Subtitle files can’t be added to media server items.
  • Subtitle size, color and position and ASS styling aren’t kept; the AirPlay device’s own subtitle settings are used. The secondary subtitle, image-based subtitles (PGS / VobSub and so on) and subtitles of videos opened with “Open URL” can’t be sent.
  • If you change the subtitle or its delay during AirPlay, the AirPlay device follows after a moment. If the video can’t be sent with subtitles, it keeps playing without them.
• Not applied on the AirPlay device: Color LUTs, enhancement shaders, video adjustments, the equalizer, volume leveling, zoom / pan / aspect ratio, flipping, subtitle appearance settings and the secondary subtitle. Use Screen Mirroring if you need these.
• Stopping: Click Return to Playback on Mac (also in the … menu), or choose This Mac with the AirPlay button, to continue on the Mac from the AirPlay device’s position. The same happens if the connection to the device is lost.
• Next file: When a file finishes during AirPlay and Raytonica moves on (according to the playback mode), or when you open another file with N / P, the library and so on, the next file keeps playing on the same AirPlay device (from where you left off in that file). If the next file is in a format that can’t be sent (such as MKV), AirPlay ends, the file plays on the Mac, and “This format can’t be sent with AirPlay, so it plays on this Mac” appears. Opening an image also ends AirPlay. When the last file finishes and playback stops, AirPlay ends (the Mac stays stopped).
• Playback position: The playback position is remembered while using AirPlay too (for local files, URLs opened with Open URL, and the position reported to a media server).

Pro feature: Play with AirPlay requires Raytonica Pro. In Lite, clicking the AirPlay button or Play with AirPlay… — PRO in the menu shows what Pro offers. Audio-only AirPlay and Screen Mirroring are macOS features, so they also work in Lite.

6. Tags

Tagging basics

• Quick tag: 1–9 toggles the tag in the corresponding slot on the current file. Slots follow the tag order (the first tag is 1). If you press the key for a slot that has no tag yet, a message such as “No tag in slot 3 yet. Press T to create a tag.” appears (the same for ⌥+1–⌥+9). You can create tags from the tag list with T.
• Tagging from the list: Use the Tags tab in the inspector, or press T, to pick, remove or create tags (right after T you can also use 1–9 / ↑ ↓ + Enter; Esc ends it).
• Tagging folders: Tag folders from the tag button that appears when you select a folder in Grid mode, or from Tag… in the selection bar that appears at the bottom of the contents when multiple items are selected (when the column is narrow, the buttons show only their icons) (also available as Tag… in the right-click menu). For a single folder or file, use Tags ▸ in the right-click menu to add or remove tags (in List, Column, Gallery and Grid views, All Files, tags, playlists, filter results and folders in the sidebar). Select one item in the library and press T to open its tag list (in List, Column and Grid views, All Files, Recently Played, tags, playlists and filter results; press T again or Esc to close it). Subfolders inside a registered folder can be tagged too. You can also tag the parent folder of the playing file with ⌥+1–⌥+9. Tagging a folder includes every file under it in tag-based playback (transparent tagging).
• Quick tag on parent folder: ⌥+1–⌥+9 toggles a tag on the parent folder of the currently playing file.

Transparent tagging

You can tag files directly or tag folders. Tagging a folder automatically includes every file inside it in that tag’s scope, including files in subfolders.

Range tags (Pro)

You can tag part of a video (from an in point to an out point).

1. Press I to set the in point and O to set the out point. The selected range is shown in yellow on the seek bar. If you set only one of them, the range runs from the start of the file or to the end of the file.
2. Press 1–9 to tag that range instead of the file. Press it again on the same range to remove the tag.
3. While an A-B loop is active (L), 1–9 also tags the loop range.
4. Press Esc to clear the range selection. It is also cleared when you move to another file.

Range tags appear as bands in the tag’s color under the seek bar. Overlapping ranges are shown on separate rows. When no range is selected, 1–9 tags the file as before. In Lite, pressing I / O shows the Pro information, and 1–9 during an A-B loop tags the file.

• Range list (Segments tab in the inspector): The range tags of the current file are listed by start time. Click ▶ on a row to play from the start of that range. Select a row to add a note, use Set Start to Current Position / Set End to Current Position, or delete it (the same actions are in the right-click menu; the Delete key also deletes it). The start can’t move past the end, and the end can’t move before the start.
• In filters: A filter’s tag conditions match a tag whether it’s on the file (or its folder) or on a range. Exclusions work the same way: a file with even one range tagged with an excluded tag is excluded as a whole, however short the range. A file that matches only because of a range tag plays from the start of that range (the earliest matching range if there are several). If you left off inside that range, it resumes from there instead.
• Tag list in the library: When you select a tag in the library, the file list shows only files and folders that have the tag themselves (files that only have it on a range aren’t listed). When you play that tag, files with the tag on a range are included.
• Export: Range tags aren’t included in tag Export (JSON) or in Finder tag export.

Scene detection (Pro)

Raytonica finds scene changes in the playing video automatically, so you can tag whole scenes.

• Scene list: In the inspector’s Segments tab, choose Scenes at the top. If the video hasn’t been analyzed yet, detection starts right away (it runs even while playing; about 2 minutes for a 1-hour video), and the scenes are listed with thumbnails. Click ▶ on a row to play from the start of that scene
• Tagging scenes: Selecting one scene makes it the I / O range (shown in yellow on the seek bar), so 1–9 adds a range tag to it. Select several scenes with ⌘ / Shift and press 1–9 to tag each of them at once (if all of them already have the tag it is removed from all; otherwise it is added to the ones that don’t). Range tags on a scene are shown as colored dots on its row
• Moving between scenes: In videos without chapters, [ / ] move to the start of the previous / next scene (videos with chapters still use chapters). Scene changes are shown as thin lines on the seek bar
• Snapping I / O to scene changes: When you press I or O within 1 second of a scene change, the point moves to the change. Turn this off with Snap I / O to scene changes in Settings > Playback
• From Visual Search: Control-click a scene in the Visual Search results and choose a tag under Tag This Scene to add or remove a range tag on the scene that contains it. If the video’s scenes haven’t been detected yet, they are detected first (a notice appears at the bottom)
• Right-click in the library: Detect Scenes in the right-click menu of files, folders, multiple selections, tags, playlists and filter results detects the videos that haven’t been analyzed yet (the videos inside, for a folder) first
• Videos you play are detected in the background: After you stop playback, the videos you played are analyzed in the background (it waits while playing or scanning). The whole library is never analyzed at once
• Similar shots are merged: With Visual Search (Pro) turned on and its model installed, the frames on both sides of each change are compared, and similar shots are merged into one scene (so a quick camera swing is less likely to be taken for a cut). Without it, the video is split at every cut where the picture changes sharply
• What can be detected: Local and NAS videos in your library (while connected). Images, audio, URLs and media-server videos are not supported. Slow transitions such as dissolves and fades may be missed

Managing tags

Manage your tag list under Tags in the Library Browser sidebar (B key):

• Click + in the heading to create a new tag.
• Click the color dot to change the tag color (10 preset colors).
• Drag and drop to reorder tags (the order maps to quick-tag slots 1–9; the number on the left of each row is its slot).
• Right-click → “Delete” to delete a tag (a tag used by a filter can’t be deleted; the menu shows why).
• Select a tag to list the files and folders with that tag as a table on the right (Name / Path / Kind / Size / Created / Modified / Last Played; click a column header to sort). The header shows the count and a Play button.
• Click to select; double-click or press Return to play a file or open a folder.
• Play in the header, or playing a file from the list, makes the tag the playback target (the toolbar shows “Tag “name””), and N / P move through the files with that tag. This is a temporary narrowing, separate from saved filters, and is not added to the filter list.
• Right-click to Play, Show in Finder, Add to Playlist, or Remove Tag (folders also offer Show in Library and Play This Folder).
• Select 2 or more items (Cmd+Click / Shift+Click / Cmd+A) to remove the tag, tag, or add to a playlist in bulk from the bar at the bottom or the right-click menu.

Writing tags to Finder (Pro)

Turn on “Also write tags as Finder tags” in Settings > Library to reflect the tags you add or remove in Raytonica as Finder tags, so you can find files by tag in Finder and Spotlight too.

• It works one way, from Raytonica to Finder. Changing tags in Finder does not affect Raytonica.
• A tag on a file goes on that file; a tag on a folder goes on the folder itself.
• Tags that were already in Finder are left alone. When you remove or delete a tag in Raytonica, only the tags Raytonica wrote are removed from Finder.
• Turning it on also writes the tags you already have. Turning it off keeps the tags already written; “Remove Written Tags from Finder” removes only the tags Raytonica wrote (and turns writing off).
• Files on an offline drive or NAS are updated when it’s connected again.
• When you remove a folder from the library, its files keep the Finder tags already written.

7. Filters

A filter is a saved preset of tag conditions. Use filters to play only files that match a specific tag combination.

Creating and editing filters

Manage filters under Filters in the Library Browser sidebar. Selecting a filter shows the files that match it (the result table) in the middle and its conditions on the right.

1. Click + in the heading to create “New Filter” right away; the cursor moves to its name field (if the name is taken, a number is added, e.g. “New Filter 2”).
2. Name & Color: The name is committed when you press Return or click elsewhere. An empty name or one used by another filter can’t be committed and is flagged in red (clicking elsewhere restores the previous name). Click the dot to the right of the name to pick a color.
3. Standard: Use “Add Tag…” to add tags to “Include Tags” and “Exclude Tags”. With two or more include tags you can choose “Any” or “All”. Click a tag’s ✕ to remove it.
4. Advanced: Write boolean expressions like tagA AND NOT tagB OR tagC. Tags assigned to a folder apply to the files inside it, just as in Standard.
5. File Types: Check Video / Audio / Image to restrict the matching scope (at least one stays selected).
6. Folders: Limit the scope to specific folders via INCLUDE / EXCLUDE folders (details below).
7. Changing a condition updates the result table right away, and changes are saved automatically (there is no Save button). Press ⌘Z (Edit > Undo) to undo changes one at a time. An expression is saved shortly after you stop typing.
8. In the result table, click to select and double-click or press Return to play (the filter becomes the playback target). ⌘/⇧-click to select several files, then tag them or add them to a playlist from the bar at the bottom or the right-click menu. The order you sort by with the column headers becomes the playback order while the filter is applied.
9. Play with This Filter in the header applies the filter and starts playback. Export saves the results as CSV / JSON (also available via File > Export Filter Results). The “…” menu has “Save as Playlist…” and “Delete Filter”.
10. Drag and drop filter presets in the sidebar to reorder them (the order maps to quick-filter slots 1–9). You can also right-click a filter in the sidebar → “Play with This Filter”.

Editing never applies a filter automatically. A filter only affects playback when you use “Play with This Filter”, play from the result table, or apply it as described in “Applying filters” below. If you edit the filter that is currently applied, the file being played keeps playing; only the next candidates, the filmstrip and the count badge switch to the new conditions. Renaming alone does not change the candidates either.

Folder conditions

In addition to tag conditions, you can restrict a filter’s scope to specific folders.

• INCLUDE folders: Only files under the listed folders are matched (when empty, every registered folder is in scope).
• EXCLUDE folders: Files under the listed folders are removed from the result.
• Include subfolders (checkbox):
  • On (default): Files in subfolders of the listed folder are also matched.
  • Off: Only files placed directly in the listed folder are matched; subfolders are skipped.

Click ”+ Add folder” to open a tree picker. Registered folders appear as roots; clicking the ▶ chevron lazily loads and expands their subfolders. You can add any folder at any depth to INCLUDE / EXCLUDE via the + button. When multiple registered folders share the same name, a breadcrumb (parent folder name) is shown alongside each entry.

Tag × folder combination examples

• “Favorite” tag × INCLUDE “Movies” folder → Only the favorites that live under Movies are played
• “Unwatched” tag × EXCLUDE “Archive” folder → Unwatched files outside the Archive
• No tag condition × INCLUDE “Recent” (direct children only) → A playlist of just the items placed directly in one folder

Applying filters

Click a filter in the Playing tab of the inspector (Filters), or press F and then 1–9. The playback queue updates immediately. Press 0 or pick “No Filter” to clear the filter. If you have no filters yet, Create Filter… opens the Library and starts a new filter.

Mutual exclusion with folder scope and playlists

Filters, folder scope, and playlists cannot be active at the same time (3-way last-write-wins rule). Enabling any one of them clears the other two, and a notification banner appears in the bottom-left of the screen.

Deleting a filter preset

Use the right-click menu on a filter preset row, or “…” → “Delete Filter” in the editor header, to delete a preset. A confirmation dialog is shown before deletion to prevent mistakes.

Exporting and importing filter presets

The “…” menu in the sidebar’s Filters heading (Export Filters / Import Filters) lets you save and load your filter presets as a JSON file.

• Export: Writes every filter preset to raytonica-filters.json. Tag names, folder paths, boolean expressions, and file-type conditions are all preserved.
• Import: Loads a previously exported JSON. Presets with the same name are overwritten. Tags and folders that don’t exist on the importing Mac are handled as follows:
  • Standard presets: Unresolved tags / folders are dropped from the condition (the preset itself is still created).
  • Advanced presets: If the boolean expression refers to a tag that can’t be resolved, the entire preset is skipped.
• After import, a summary shows “Added N / Updated M / Skipped K”, with a detailed list of skipped presets and unresolved dependencies.

Use this to migrate filter presets to another Mac or to back up a complex setup.

8. Playlists

Playlists are named queues with a frozen playback order. While filters are “tag-condition queries that re-evaluate every time”, a playlist freezes the files and their order so you can keep favorite collections or manually-ordered queues for the long term.

Creating a playlist

Manage playlists under Playlists in the Library Browser sidebar. You can create a playlist by freezing a filter result, or by right-clicking files or folders and adding them.

1. In the filter editor, choose “…” → “Save as Playlist…” in the header. The current filter result is frozen into a Snapshot playlist on the spot.
2. Clicking + in the sidebar’s Playlists heading creates an empty playlist. You can add files to it later as described below.

Switching playlists while playing

Pick the playlist to play in the Playing tab of the inspector (Playlists), or press Y.

• Choosing a playlist switches playback to it and resumes where you left off (or from the start). Any filter or folder playback is cleared
• Right after Y, press 1–9 to pick one of the first nine playlists, or use ↑ ↓ and Enter
• Choosing the playlist that is already playing does nothing (clear it with the ✕ on the playback chip in the center of the toolbar)
• Press Y or Esc to end selection mode

Adding files to a playlist

Right-click in any of the following places, choose Add to Playlist, and pick the playlist (or New Playlist…).

• Files in the library: If several files are selected, all selected files are added
• Folders in the library: Adds the files in the folder (including subfolders). Several selected folders can be added at once
• Rows in the filter result table
• Files in the playback history and the filmstrip
• The file that is playing: Right-click the video area, or press A to show the menu

Files are added to the end (a playlist you have reordered keeps its order). Files already in the playlist are not added twice, and the number of files added and already present is shown on screen.

Editing a playlist

The playlist you select in the sidebar is shown as a table on the right (# / Name / Path / Kind / Size / Created / Modified / Last Played). The header shows the item count (and how many files are missing, if any), the Play / Stop button, and a “…” menu.

• Click: Select (Cmd+Click / Shift+Click for multiple). Double-click or press Return to play the playlist from that file.
• Manual reorder: Drag rows to your preferred order. The order is saved and becomes the playback order. Selected rows move together.
• Sort by column: Click the Name / Path / Kind / Size / Created / Modified / Last Played header to sort ascending / descending; the result is saved (this overwrites the manual order).
• Remove: Right-click a row → “Remove from playlist”, or select rows and press Delete (asks for confirmation). Multi-select is supported.
• Rename: Double-click the name, or use “…” → “Rename…”.

Playing a playlist

• Right-click a playlist in the sidebar and choose “Play”, or click the Play button in the header. The playing playlist shows a speaker icon in the sidebar.
• Activation starts playback from the last-played file (or the first file if there’s no history).
• During playback, N / P walk through the playlist. The global playback mode (Normal / Repeat all / Shuffle) still applies.
• Playback position and history are stored per playlist, so you can switch between playlists and resume each from where you left off.

While a playlist is playing

While a playlist is playing, a chip showing the playlist (icon + name + current position / item count) is always shown in the center of the toolbar, to the right of the file name. Click the chip to open Playing in the inspector, or click its ✕ button to deactivate the playlist.

Exporting and importing playlists

You can export and import playlists as JSON files.

• Export: Right-click a playlist in the sidebar and choose “Export Playlist”, or use “…” → “Export Playlist” in the header, to save the selected playlist as playlist-{name}.json. The files and their display order (including manual reordering) are written out.
• Import: Use the “…” menu in the sidebar’s Playlists heading → “Import Playlist” to load a JSON. If a playlist with the same name already exists, you’re asked to confirm overwriting.
• Files are identified by path, so any file whose path doesn’t exist on the importing Mac is skipped. After import, a summary shows “Added N / Updated M” along with a list of paths that couldn’t be resolved.

Use this to migrate to another Mac or to back up a manually-ordered favorites collection.

Relationship with filters and folder scope

Playlists, filters, and folder scope are mutually exclusive in a 3-way last-write-wins fashion. Activating a playlist clears any active filter or folder scope, and vice versa. A notification banner appears in the bottom-left of the screen when the active mode changes.

9. Library Browser

Press B or click the sidebar button at the left end of the toolbar to open the Library Browser. When the main window is maximized it can be shown on the left side of the main window; the button at the bottom left detaches it into a floating panel.

Sidebar

Use the sidebar on the left of the Library Browser to choose what to look at (a source). The contents of the selected source appear on the right.

• Use + in each heading to add a folder or create a filter / playlist / tag. The “…” menu holds Export / Import.
• Click a heading’s name (with the › on its left) to hide or show what’s under it. Hidden headings stay hidden the next time you open the library. Keyboard shortcuts such as F → 1–9 for filters and 1–9 for tagging keep working while a heading is hidden.
• Right-click an item for what you can do with it (play, Show in Finder, delete, and so on).
• After clicking the sidebar, ↑ / ↓ move between items.

All Files / Recently Played

Files are listed in a table (Name / Path / Kind / Size / Created / Modified / Last Played). Click a column header to sort. Size, Created and Modified are read in the background after the list opens, so for files on a NAS they may appear a moment later (shown as “—” until then). The folder list view and the tag list have the same columns (folder sizes are not shown). Right-click a column header to show or hide columns (the Name column is always shown). Drag a column header left or right to change the column order. Each table remembers its visible columns, widths and order (the playlist and filter result tables too).

• Click: Select (Cmd+Click / Shift+Click for multiple)
• Double-click / Return: Play. Playing from here clears any filter, playlist, or folder scope.
• Right-click: Show in Finder / Tags ▸ (for a single file) / Add to Playlist / Analyze for Visual Search / Detect Scenes (Pro)
• Play button at the top: “All Files” clears filters etc. and plays from the whole library; “Recently Played” starts from the most recently played file.
• Use the search field at the top to filter by file name.

Duplicates

Finds files with the same contents in your library. Click Find Duplicates to start (progress is shown and you can cancel). The results stay until you quit the app, and the sidebar shows how many groups were found.

• Files of the same size are compared at 16 positions from beginning to end. This can take a while if many files are on a network drive.
• Click Check Exact Match in a group’s header to compare the files in that group in full (this can take a while for large videos). The result is shown as Identical or Partly different (they differ outside the compared positions — for example, one copy may be damaged). Use it before deleting files.
• Files in offline folders and Missing Files are not included.
• Results are shown in groups (count and size; each file’s path, number of tags, and last played date).
• Double-click / Return: Play
• Right-click: Show in Finder / Remove from Library (removes the files from the library after confirmation; their tags and playback positions are removed as well. Nothing happens to files on disk — delete unwanted files in the Finder).

Missing Files

Lists files that can no longer be found on disk — for example because they were deleted inside a registered folder or moved outside of one. Raytonica checks when the app opens and when it detects changes in a folder. When new missing files are found, a message such as “Couldn’t find n file(s)” appears at the top of the screen.

• Missing files are not removed from the library automatically. Their tags, playlists, and playback positions are kept, and if a file reappears inside a registered folder (including after a move or rename) it is restored automatically.
• Missing files are excluded from playback (shuffle, next file, and so on).
• Locate… (when one file is selected, or double-click): Choose the file’s new location to relink it while keeping its tags. The new location must be inside a registered folder (register that folder first if it isn’t). If the new location is already in the library, the two entries are merged, keeping the tags from both.
• Remove from Library (the selected files, or … → Remove All from Library): Removes the files from the library after confirmation. Their tags and playback positions are removed as well. Nothing happens to files on disk.

Folders

Select a folder in the sidebar to show its contents. The view modes, search, and keyboard navigation below apply to the folder view.

• The top shows the folder name, its file count, and a Play button (play this folder).
• Click: Select (Cmd+Click / Shift+Click for multiple). In Column mode, clicking a folder opens its contents in the next column.
• Double-click / Return: Open a folder or play a file. Playing from inside a folder makes the folder selected in the sidebar the playback target (folder scope), and N / P move within that folder.

View modes

Switch between four modes with the buttons at the top of the folder view:

Search

Type in the search bar to filter the selected folder by file name or folder name. Use the Folders / Files checkboxes below the search bar to restrict the search scope.

To narrow down by tag, select the tag under Tags in the sidebar.

File type filter

The Video / Audio / Image toggle buttons in the folder header restrict which media types appear in the browser.

Keyboard navigation (Library Browser)

Multi-select and bulk actions

• Cmd+Click: Toggle individual selection.
• Shift+Click: Range select.
• Selecting 2 or more items shows an “n Selected” bar floating at the bottom of the contents (the contents do not shift) with Tag… (adds or removes tags across the selection, even when folders and files are mixed), Add to Playlist, and Remove from Library (the trash button, when registered folders are selected; asks for confirmation). × clears the selection.
• Right-clicking a selected item offers the same bulk actions (Tag… / Add to Playlist / Show in Finder / Delete (n), or Register (n) when only unregistered folders are selected).
• In All Files and Recently Played, selecting 2 or more files shows the same bar for tagging and adding to a playlist.

Context menu

Right-click a folder row:

• Play files in this folder (set folder scope)
• Show in Finder
• Tags ▸ (choose a tag to add it to or remove it from the folder)
• Add to Playlist / Analyze for Visual Search / Detect Scenes (Pro; the videos inside)
• Reconnect… (only for folders shown as offline)
• Remove from Library (registered folders) / Register Folder (unregistered folders)

Right-clicking a folder in the sidebar offers the same “Play This Folder”, “Reconnect…”, “Remove from Library”, and so on.

Right-click a file row:

• Show in Finder
• Open with another app (when a compatible app is available)
• Tags ▸ (choose a tag to add or remove it)
• Add to Playlist / Analyze for Visual Search / Detect Scenes (Pro)

Saved URLs (Pro)

Keep URLs you watch often in the sidebar under Saved URLs, with a name, so you can open them quickly.

• To save: click the bookmark button at the right of a recent URL in Open URL (or right-click it and choose Save URL), choose File > Save Current URL while a URL is playing, or click + next to Saved URLs in the sidebar (enter the URL and a name).
• Name: for a video site page opened with yt-dlp, the page title; otherwise the URL’s display name (“file name — host”). You can rename it later.
• The same URL isn’t saved twice (“Already saved” appears if it’s already there).
• Each row shows the name and host, plus “Resume at 12:34” if there’s a position to resume from. Double-click a row, or select it and press Return, to open it (it resumes just like Open URL). Selecting one shows its URL with Open and Copy URL on the right.
• Right-click: Open / Rename… / Copy URL / Delete
• Drag and drop to reorder.
• Saved URLs aren’t added to your library (no tags or playlists).
• Export / Import: use the “…” menu on the Saved URLs heading (Export Saved URLs / Import Saved URLs) to write your saved URLs to a JSON file and read them back — handy for moving to another Mac or keeping a backup.
  • Export: saves all your saved URLs, with their names, URLs and order, as raytonica-saved-urls.json. Resume positions aren’t included, since they’re viewing state that belongs to each Mac.
  • Import: adds the URLs to the end of the list (existing URLs aren’t changed or removed). URLs that are already saved are skipped, and URLs that aren’t http/https are ignored. When it finishes, you’ll see “N URL(s) added, M skipped” and a list of the ignored URLs.
  • If you choose a file that isn’t a Raytonica saved URL export (a damaged file, or a tag or playlist file, for example), “Invalid File” appears and nothing is imported.

Media servers (Jellyfin / Emby, Pro)

Use + next to Media Servers in the sidebar to connect to a Jellyfin or Emby server (server URL, user name and password). You can add several servers and users.

Servers on your local network can use http:// (for example http://192.168.1.10:8096). For servers you reach over the internet, use an https:// URL. The first time you connect to a server on your local network, macOS may ask you to allow access to the local network.

• Selecting a server shows its libraries and Continue Watching. Double-click a library, series or season to open it; use < to go back.
• The table shows name, year, length and progress (watched or %). The search field at the top right searches within the current library.
• Double-click a video to play the original file (no transcoding). It starts where the server says you left off, and the position is sent back to the server while playing and when you stop (the server marks it watched).
• Control-click items and choose Mark as Watched or Mark as Unwatched to change their watched status (you can select several). Using it on a series or season changes all of its episodes.
• Server videos aren’t added to your library (tags and filters).
• Right-click and choose Remove Server to delete the sign-in from Raytonica (nothing changes on the server). Your password isn’t stored; the token the server issues is kept in the keychain.

Visual search (Pro)

Find scenes by describing what’s on screen in plain words, like “sunset at the beach” or “a dog in the snow” — in English, Japanese and other languages.

• Turn on Use visual search in Settings > Library > Visual Search. The first time, about 360 MB of model files (a Mac conversion of Google’s SigLIP 2) are downloaded. Progress appears in Settings and at the bottom of the sidebar. To stop, click Cancel or turn the setting off.
• Once the model is installed, videos in your library are analyzed three at a time, in two passes:
  • Quick pass: first, the whole library is skimmed at one frame every 30 seconds. Videos become searchable as soon as their quick pass is done.
  • Detailed pass: once the quick pass has covered everything, videos are analyzed again at a frame every 5 seconds (every 10 seconds for videos an hour or longer) so smaller scenes can be found; runs of similar frames are thinned out.
  • In each pass, recently played videos go first, then the newest files. Videos you add to the library during analysis are picked up automatically and, as new files, come up soon.
  • Videos you play, and videos you pick with “Analyze for Visual Search” in the right-click menu, are analyzed first. As soon as one of the videos being analyzed finishes, that video goes through both the quick and the detailed pass (analysis is paused during playback, so it starts when you stop playing). The menu item is on folders, files, multiple selections, tags, playlists and filter results in the library; for a folder, the videos inside it are analyzed. If everything you picked is already analyzed, you’ll see “nothing to analyze”.
  • Progress appears in Settings (“Quick pass: N of M videos”, “Detailed pass: N of M videos” and an estimate of the time left; hover over the “?” for an explanation of the two passes) and at the bottom of the sidebar. The time left is an estimate based on how fast analysis has been going; it appears after a few videos are done and doesn’t include time spent paused during playback.
• Analysis marks: In the library, a mark appears next to the names of files and folders (in List view and All Files, in the Visual Search column). For files, ◑ = quick pass done, ● = detailed pass done, ⚠︎ = couldn’t be read (no mark = not yet). For folders, covering every video inside: ● = all done in detail, ◑ = partly (hover to see the counts). Marks appear only while Visual Search is in use.
• Analysis happens only on this Mac. Your videos are never uploaded. Only the model is downloaded.
• Analysis pauses during playback and library scans, and resumes where it left off. Files on offline drives or NAS are skipped and analyzed once they’re connected.
• Results (the index) are stored outside your library, in the app’s data folder. Changed files are analyzed again, and results for files removed from the library are deleted.
• Files that can’t be read (damaged, or with no video) are skipped and not retried until the file changes. Choosing “Analyze for Visual Search” in the right-click menu tries them again.
• If a file can’t be reached (for example, the connection to a NAS drops for a moment), it isn’t treated as unreadable and is analyzed again later. If several files in a row can’t be reached, analysis pauses and resumes after about a minute.
• MP4 / MOV files are read with macOS; MKV, WebM and other formats are read with the built-in mpv.
• Delete Model and Index removes the model and all analysis results and turns the feature off.

Searching: select Visual Search in the library sidebar, describe the scene in the search field, and press Return.

• Matching scenes appear as thumbnails with timestamps (up to 120 scenes; nearby scenes from the same video are combined, and at most 5 scenes per video). The number of results (“N scenes in M videos”) appears above the list, and the Sort menu on the right lets you choose Best Match, File Name, or Recently Played (scenes within a video stay in best-match order; your choice is remembered). Click one to play from that point, and the search results become what you’re playing from (a “Search “…”” chip appears in the toolbar; like filters, folders and playlists, whichever you chose last wins).
• While playing from search results, N / P move through the matching videos in the order shown in the list, each starting at its best-matching scene (if you’d already watched part of a matching scene, it continues from there). Purple marks above the seek bar show the video’s other matching scenes.
• Click × on the chip to stop playing from the search results. Click the chip itself to open Visual Search in the library.
• Control-click a scene for Play from This Scene, Tags (check to add or remove), Tag This Scene (adds a range tag to the scene containing it; see Scene detection), Add to Playlist, Show in Library, Show in Finder, and Open with.
• Only analyzed videos are searched (the line under the search field shows “Searching N of M analyzed videos”). Videos on offline drives or NAS don’t appear in the results.
• Describe what’s visible, like “sunset at the beach”, “a dog in the snow” or “a person singing on stage”. You can’t search by what people say or by people’s names.
• The first search takes a few seconds while the text model loads.

Searching the playing video (⌘F): While a video is playing, press ⌘F (Library > Visual Search… in the menu bar) to show a search field above the player. Type a description and press Return to search only the current video.

• Matching scenes appear as purple marks above the seek bar, and the field shows “N scenes” (nearby scenes are combined; up to 20 scenes close to the best match). Only scenes that clearly match are shown, so scenes that merely have a person in them don’t count.
• Press ⌘G for the next matching scene and ⇧⌘G for the previous one (or use ‹ › in the field). It wraps around at the ends. If there are no matching scenes, the status in the field (such as “No matches”) shakes to let you know.
• When you move to another video, the same description is searched in that video. For a video that hasn’t been analyzed yet, “This video hasn’t been analyzed yet” appears below the search field. Click Analyze next to it to analyze that video first (analysis runs while playback is paused); the search runs again when it’s done.
• Search Library opens Visual Search in the library with the same description. Press Esc or click ✕ to close the field.
• When the library window is in front, the library is shown beside the player, or nothing is playing, ⌘F opens Visual Search in the library with the cursor in the search field.

10. Video and Audio Adjustments

Open Settings and choose Video & Audio. Video adjustments and the equalizer are shown together on one page.

Video adjustments

When every value is 0, the Reset button is hidden. Settings are persisted.

Color LUTs (Pro)

You can apply a 3D LUT (.cube format) to videos while they play, for example to check footage shot in Log with its intended look.

• Click Import… and choose a .cube file. Raytonica copies it in and adds it to the list (it keeps working even if the original is on a drive you unplug).
• Choose a LUT from the list to apply it to every video; choose None to turn it off. Delete removes the selected LUT from the list.
• LUTs aren’t applied to images, and the CPU load increases somewhat while a LUT is applied.
• A video that has finished and stopped shows the change the next time it plays.

Enhancement Shaders (Pro)

In Settings > Video & Audio > Enhancement Shader, you can sharpen or upscale videos on the GPU while they play.

• FSR (upscaling, live action): AMD FidelityFX Super Resolution. It takes effect when the video is shown larger than its original size, such as a 1080p video on a 4K display or in full screen.
• CAS (sharpening): AMD FidelityFX Contrast Adaptive Sharpening. It sharpens edges at any size and adds almost no load.
• Anime4K (upscaling, anime): upscaling made for anime. It takes effect when the video is shown larger than its original size. It’s the heaviest, roughly doubling the GPU load.
• Click Add Shader… to add your own mpv shader (.glsl). Raytonica copies it in and lists it below the built-in ones. Delete removes only shaders you added.
• The selected shader applies to every video and works together with a color LUT (it’s applied after the LUT). It doesn’t apply to images or during AirPlay.

Audio Output

In Settings > Playback > Audio Output, you can play Raytonica’s sound through a different output than the system (headphones, an audio interface and so on).

• Use System Setting (the default) plays through the output chosen in macOS Sound settings
• If the device you chose is disconnected, sound plays through the system output and a notice appears at the bottom of the screen. It switches back when you reconnect the device. While it’s disconnected, the list shows “(not connected)”
• The setting is kept the next time you open Raytonica. It doesn’t apply while playing with AirPlay

Audio equalizer (10-band)

Adjust 10 bands from 31Hz to 16kHz, ±12 dB each, via vertical sliders. Settings persist across launches.

Volume leveling (Pro)

Use Volume Leveling on the same page to even out loud and quiet parts while playing (quiet dialogue and loud effects, or differences between videos).

• Light: Narrows the gap while keeping the dynamics.
• Strong: Keeps the volume nearly constant.
• It’s applied after the equalizer, and the setting persists across launches.

Audio Delay (Fixing Audio Sync)

Choose Audio from the … menu at the right end of the toolbar to fix audio that’s out of sync with the picture.

• Use the stepper in ±0.1-second steps (up to ±30 seconds). + plays the sound later and − earlier. If you hear the sound before the picture, use +
• While it isn’t 0, the menu item shows the value, such as “Audio +0.3s”. The reset button sets it back to 0
• It returns to 0 when you open another file (like the subtitle delay)
• For files with two or more audio tracks, you can also choose the track in the same popover
• It doesn’t apply while playing with AirPlay

11. Subtitles

Choose Subtitles from the … menu at the right end of the toolbar to open the subtitle popover.

• Auto-detect: Raytonica automatically loads subtitle files with the same name as the video (SRT / ASS / VTT / SSA, etc.).
• Track selection: Pick from embedded tracks and external files.
• Manual load: “Load file…” lets you pick any subtitle file.
• Delay: Adjust in ±0.1-second steps (up to ±30 seconds) using the stepper at the bottom of the popover. It returns to 0 when you open another file.
• Appearance: Choose “Appearance…” in the popover (or Settings > Playback > Subtitle Appearance) to change the subtitle size (50–200%), vertical position, text color, and outline thickness and color. Changes apply right away to the playing subtitles and to every file. “Restore Defaults” puts them back
  • ASS/SSA subtitles define their own colors and positions. By default only the size is applied to them; turn on “Apply to ASS/SSA subtitles too” to apply the colors, position and outline as well
• Second subtitle (Pro): Use “Second (top)” in the popover to show another subtitle at the top of the screen at the same time (for example, the original language below and your own language above, for language learning). The second subtitle is shown as plain text without ASS styling, and its size and colors follow Appearance. Subtitles loaded from a file or found online can be chosen too. The subtitle already shown as the first one can’t be chosen. The delay applies to both, and the second subtitle turns off when you open another file. In Lite, choosing from “Second (top) PRO” shows what Pro offers

Search Online (Pro)

Choose Search Online… in the subtitle popover to search for subtitles on OpenSubtitles.com and download them.

• How it searches: Raytonica searches by the video file’s hash (a value calculated from the beginning and end of the file) and its file name. Results are grouped by the languages you chose, in the order you chose them. Within a language, subtitles whose hash matches (made for that exact file) are marked and listed first, followed by the most downloaded. You can edit the search text, which is drafted from the file name.
• Languages: The app’s display language is selected by default. You can select several, and your choice is remembered for next time.
• Download: Select a subtitle and click Download (or double-click it) to save it, load it, and show it. The number of downloads left today is shown.
• Download limit: Without signing in, you can download 5 subtitles a day; a free OpenSubtitles account allows roughly 10–20 a day (OpenSubtitles sets the limits). When you reach the limit, the time it resets is shown. Searching doesn’t count toward the limit. If too many requests are sent in a short time, Raytonica waits and retries once automatically when the wait is only a few seconds; otherwise it shows how many seconds to wait.
• Account: In Settings > Playback > Online Subtitles (OpenSubtitles), click Sign In… to sign in with your OpenSubtitles username and password (you can open the same sheet from Sign In… at the bottom of the search window). If you don’t have an account, use the link there to create one for free. While signed in, “Signed in as " is shown, and **Sign Out** removes the account from this Mac (the information on this Mac is removed even if OpenSubtitles can't be reached). Your password is stored in this Mac's keychain and used to sign in again automatically when your session expires. If that fails (for example, after you change your password), you're asked to sign in again.
• Where it’s saved: By default, downloaded subtitles are saved inside the app (~/Library/Application Support/app.raytonica.Raytonica/Subtitles/) and load automatically the next time you open the same video (saved subtitles still load if you go back to Lite). If you delete a saved subtitle file, it is no longer loaded automatically. Turn on Save downloaded subtitles in the video’s folder in Settings > Playback > Online Subtitles (OpenSubtitles) to save them next to the video as video name.language.srt (if a file with that name exists, a number is added; nothing is overwritten). If the video’s folder isn’t writable (read-only or no permission), or the video was opened from a URL, subtitles are saved inside the app even when this is on, and you’re told so.
• Videos opened from a URL: If the server supports partial downloads (Range requests), the hash can be used too. Otherwise, and for HLS streams, only the name is used.
• What is sent: When searching, the file’s hash, its file name (the search text) and the languages are sent to OpenSubtitles.com. Raytonica connects only when you click Search or Download, never just because you opened a video.

Pro feature: Searching and downloading subtitles online requires Raytonica Pro. In Lite, clicking Search Online… PRO shows what Pro offers (see “15. License”).

12. Media Info

Use the Info tab in the inspector, choose Media Info from the … menu at the right end of the toolbar, or press ⌘I (Toggle media info panel in the View menu), to show the technical information for the currently playing file (codec, resolution, bitrate, sample rate, file size, and more). While the inspector is open, ⌘I shows or hides the Info tab. The I key sets the in point for range tags (you can also assign a single key to media info under Settings > Shortcuts).

• Video / audio: shows both video and audio info
• Image: resolution, file size, and format only (codec etc. omitted)
• Format: file extension (MP4 / MOV / MKV, etc.)

The full file path is also shown at the bottom of the panel — click the path row to reveal the file in Finder.

13. Screenshots

Press Shift+S, or choose Screenshot in the … menu at the right end of the toolbar, to save the current frame as an image.

• Copy to clipboard: Choose Copy Screenshot in the Video menu (⇧⌘C) or in the … menu to copy the frame to the clipboard without saving
• Format: In Settings > Playback > Screenshots, choose PNG (the default), JPEG or HEIC
• Include subtitles: In the same place, choose whether subtitles appear in the image (included by default)
• Save to: By default you choose where to save each time. Use Choose Folder… to save straight to a folder without asking (Ask each time switches back). File names include the playback position, such as “Movie_02m05s.png”, and a number is added instead of overwriting an existing file

14. Settings

Choose Raytonica → Settings… in the menu bar (⌘,) to open Settings.

The Settings window always stays in front of other windows (so the floating Library window doesn’t hide it). Drag an edge of the window to resize it; it reopens at the size you chose.

When the on-disk thumbnail cache grows beyond 1 GB in total, the least recently used thumbnails are removed automatically (checked once a day).

Subtitle track selection and delay are handled from Subtitles in the toolbar’s … menu, not in Settings (see “11. Subtitles”).

Customizing shortcuts

1. Open Settings > Shortcuts.
2. Click the key of the action you want to change. It changes to “Press a key…”.
3. Press the new key. It is saved right away (press Esc to cancel).
4. If you press a fixed shortcut (R / V / S / 1–9 / arrow keys, etc.) or a key another action already uses, the row shows the reason in red and nothing is saved. You can press another key straight away.
5. Use Reset All to Defaults at the bottom to restore every shortcut after confirming.

Deinterlacing

In Settings > Playback > Deinterlace, you can remove the comb-like stripes that appear in interlaced video such as old DVDs and TV recordings.

• Auto (the default): applied only to video marked as interlaced. Ordinary videos are left alone
• On: applied to all video (for files that show stripes even though they aren’t marked as interlaced)
• Off: not applied
• Changes apply right away to the playing video. CPU use goes up slightly

Hardware decoding

You can toggle hardware decoding ON/OFF in Settings > Playback (default: ON). Codecs that don’t support hardware decoding fall back to software decoding automatically. The change takes effect on the next file load.

Automatic updates (Sparkle)

Raytonica uses Sparkle Framework for automatic updates.

• Manual check: Pick “Check for Updates…” from the Raytonica menu (right below About) to look for a new version on demand.
• Automatic check: In Settings > General > Updates, the “Automatically check for updates” toggle controls whether Raytonica checks for a new version in the background at launch (default: ON).
• What a check sends: While automatic checks are on, each check sends only the app version, edition (Lite / Trial / Pro / Studio), macOS version and display language, anonymously. This is used to count how many copies are in use. Nothing that identifies you or your Mac (IDs, the Mac’s name, serial number, model, etc.) is sent. If you turn automatic checks off, these values aren’t sent even when you check manually.
• When a new version is available, a dialog with release notes appears. Installing the update restarts Raytonica and swaps in the new version automatically.
• Only updates that pass Sparkle’s EdDSA signature verification are installed, so tampered builds cannot be substituted.

Beta period: During the closed beta, updates ship from the beta channel. After v1.0 the stable channel becomes the default, and a setting will let you opt in to the beta channel.

Reduce motion (accessibility)

When Reduce motion is turned on in macOS (System Settings > Accessibility > Display), Raytonica follows it.

• Animations that involve movement — opening and closing the filmstrip, and scrolling or moving between columns in the library — switch instantly without animation.
• The sidebar (library) and the inspector are standard macOS panels, so they slide open and closed regardless of this setting.
• Elements that slide in from the edge of the window (scan progress, notifications, the new-tag field, etc.) appear with a fade only.
• On-screen displays such as volume and speed still fade in and out as usual.

15. License (Lite / Pro)

Raytonica has a free Lite edition and a paid Pro edition.

Features not available in the free edition

Lite and Pro differ only in which features they include. You can create as many tags, filters and playlists as you like, export / import tags, filters and playlists, export filter results (CSV / JSON), and use filter expressions and the Mini Player, in Lite too.

Try Pro for 14 days

You can try Pro features for 14 days without leaving Lite. Click Try Pro for 14 Days in Settings > License or on the page that explains a Pro feature, or Try Pro on the Getting Started card. When the trial starts, “Pro trial started (14 days left)” appears on screen (and at the bottom of the Settings window, if it’s open).

• Only days you use the app count. Days you don’t open the app aren’t counted (opening it several times in one day counts as one day).
• One trial per Mac.
• During the trial, “Pro trial · N days left” appears at the bottom of the library sidebar, in the app menu (Raytonica), and in Settings > License. You’ll get a notice when 3 days are left and on the last day.
• When the trial ends, Pro features stop working, but what you created during the trial is kept. Range tags stay visible in the list and during playback, and the visual search index is kept, so if you buy Pro you can continue without re-analyzing.

When you use a Pro feature in Lite

Pro features stay visible in Lite and carry a PRO badge (in menus: “Name — PRO”). Clicking one or pressing its key opens a page that explains the feature (what it does, how to use it, and its limits) and what Pro includes.

• Enter License: Opens Settings > License with the cursor in the serial number field, so you can enter and activate your serial number.
• Buy Pro…: Opens the purchase page (the purchase page isn’t public yet, so this button is currently unavailable).
• Try Pro for 14 Days: Shown if you haven’t used your trial yet. Click it to start the trial right away, and the action you were trying continues (for example, if you were setting a range tag’s in point, it’s set at the position where you pressed the key). For something that was in progress, like pinch-to-zoom, just do it again.

Settings > License lists the features that aren’t available in Lite; Learn More… opens each feature’s explanation (without the list of other Pro features, since they’re all listed there).

Activating your license

• Where to find your serial number (license key): After purchase, it appears in the customer portal of Polar, which handles sales. The order confirmation email links to the portal (sign in to the portal with the email address you used to buy).
• Entering it: Paste it into the field in Settings > License and click Activate (or press Return). Spaces and line breaks — before, after, or inside the key — are removed automatically.
• When activation succeeds, a green check and “License activated (Pro)” appear, and the status changes to Pro.
• If activation fails, the reason is shown: the serial number wasn’t found / it’s already activated on the maximum number of Macs (deactivate it on a Mac you no longer use, then try again) / the key has been disabled or has expired / the license server can’t be reached / too many attempts / a server problem.
• Deactivate: Deactivate on the activated screen removes the license from this Mac (freeing up a slot).

16. FAQ

What happens if I move or rename files?

Moves and renames within the same volume are tracked automatically, preserving tags. Files on different volumes are identified separately. Records from older versions are upgraded when the file is found at its recorded path. Unmatched legacy records, including files moved before this upgrade, are retained rather than automatically deleted. Files moved outside of registered folders or deleted appear under Missing Files in the library (they are not removed automatically); use Locate… to relink them with their tags intact.

Can I use folders on NAS (network storage)?

Yes. While offline, the icon turns orange but the data is preserved. An offline folder still shows the contents recorded in your library (its folders, files and any thumbnails you’ve seen before), grayed out, so you can search, check tags and tag files as usual (the same applies when you unplug an external drive). If you try to play a file in an offline folder, a message such as “(drive name) isn’t connected — couldn’t open (file name)” appears at the top of the screen and playback stops there (Raytonica does not skip ahead to the next file). When the mount path stays the same, Raytonica detects file additions/removals and resumes scanning automatically once the folder is reachable again. Files in an offline folder are not picked by shuffle or the next-file action until the folder is connected again.

When the mount path itself changes (for example SMB remounts that add a /Volumes/Share-2-style suffix), Raytonica does not follow the new path automatically. Right-click the offline folder and choose “Reconnect…” to point it at the new path; existing files and tag associations are carried over.

If a scan fails partway through, unseen records and tags are retained. Successfully read files can still be added or updated, and the next successful scan reconciles the remaining records. Files not found during a successful scan are not deleted either; they are listed under Missing Files.

Will it slow down with a large library?

Raytonica is optimized for startup performance and stays responsive with libraries of 10,000+ items (verified on a 13,000+ file library).

I see “Couldn’t save your changes”

This appears at the top of the player when library changes (tags, filters, playlists, folder information) couldn’t be saved, for example because the disk is full. Your changes are kept until you quit the app, so free up some space and click Retry. The message disappears once the changes are saved. If you quit while it is still shown, the unsaved changes are lost.

Raytonica quit with “Library Created by a Newer Version”

If your library was last opened by a newer version of Raytonica than the one you launched, Raytonica quits without opening it to protect your data. Please use the latest version.

The library is stored in ~/Library/Application Support/app.raytonica.Raytonica/Raytonica.store. When an update changes how the library is stored, Raytonica backs up the library to raytonica-backup/ in the same folder before converting it.

Raytonica said “Couldn’t Open the Library” and quit

If the library file is damaged or in a format Raytonica can’t read, Raytonica quits without opening it so the library isn’t damaged further. The file at the location shown is left unchanged. It may be possible to restore it from a backup in raytonica-backup/, so please contact support.

How do I back up or migrate my tag data?

Use Export / Import in the “…” menu of the Tags heading in the Library Browser sidebar. Tags are exported as JSON and can be imported on another Mac or after reinstallation.

17. Shortcut Cheatsheet

Playback

Panels

Tagging