uncompiled/cornhole repository overview

⁠Cornhole - User Guide

Cornhole changes a folder of unsorted videos (phone dumps, downloads, old camera footage) into a fast swipe-through feed. You look at one video. You tap Tag, Move, or Delete. Then you move to the next video. This guide tells you how to run Cornhole on your own computer.

Read "Things to know before you start" below before your first real triage session. Here is the short version: Delete is instant and permanent. Cornhole is a tool for one person only. Do not share the URL with another person who will use it at the same time.

⁠Quick start

How Cornhole works. Point Cornhole at a folder of videos. It scans the folder and shows every video as one card in a scrolling feed, newest first. Each card gets a small thumbnail right away; a background job then keeps refining that thumbnail to a better, more representative frame, without blocking you from triaging in the meantime. Cornhole also watches the folder on its own, so a video you add or remove later shows up (or disappears) without you doing anything. For each video, you tap Tag, Move, or Delete, then move to the next one. Tagged and unsorted videos live under separate tabs, so a cleared Unsorted tab is your "done" signal.

Using the feed:

• Tap a card's video to play it, starting from the moment shown in its thumbnail. Tap the pause icon, or scroll the card out of view, to stop it.
• Drag the scrub bar under a playing video to jump to another part of it.
• Tap the speaker icon to unmute. This preference applies to every card.
• Tap Tag (tag icon) to open the tag picker. Type a new tag name, or pick an existing one from the list, to add it. Tap the × on a tag to remove it. Tags are applied together when you tap Done — until then the video stays where it is, so you can pick several tags in one visit. Leaving the sheet without Done (Escape, or tapping outside it) throws away what you staged. A video with at least one tag moves to the Tagged tab.
• Tap Move (folder icon) to file a video straight into one of your named Sorted subfolders, instead of only tagging it. Only appears if you set up a Sorted folder (Step 2).
• Tap Delete (trash icon), then confirm, to remove a video for good.
• Tap the sort icon (top right) to change the feed's order: newest first, longest or shortest first, or largest or smallest file first.
• On a desktop browser, open Settings (gear icon) and drag the Card size slider to show more or fewer cards per row.

Keyboard shortcuts (desktop browser only):

The rest of this guide covers installing and running Cornhole for the first time, then goes into more detail on each of the points above.

⁠1. Install Docker

You must install Docker on the computer with the videos.

• Mac or Windows: Install Docker Desktop⁠. Open it. Confirm it shows "Running" before you continue.
• Linux: Install Docker Engine⁠ for your Linux distribution.

The Docker image works on Intel, AMD and Apple Silicon (M1, M2, M3, M4) Macs. You do not need extra steps for either type.

⁠2. Select two folders

Cornhole needs to have access to two folders on your computer:

1. Your video library. This is the folder with the videos you want to sort.
2. A "sorted" folder (optional). Use this folder if you want a "move to a named folder" option, in addition to Tag and Delete. To set this up, create the folder. Then put empty subfolders inside it for each destination, for example Sorted/Vacation, Sorted/Funny, Sorted/Keep Forever. If you skip this step, you can still use Tag and Delete, but you will not get the option to move the video to another folder.

Write down the full paths to these folders. You will need them in the next step. Examples:

• Mac: /Users/yourname/Movies/ToSort
• Windows: C:\Users\yourname\Videos\ToSort
• Linux: /home/yourname/Videos/ToSort

Mac only: The first time you point Docker at a folder outside your home directory, Docker Desktop will ask for permission. Go to Settings → Resources → File Sharing. Add the folder there if Cornhole cannot see your videos.

⁠3. Run Cornhole

Open a terminal. On Mac, use the Terminal app. On Windows, use PowerShell. On Linux, use your terminal. Then run this command:

docker run -d \
  --name cornhole \
  -p 3000:3000 \
  -v "/path/to/your/videos:/data/videos" \
  -v "/path/to/your/sorted:/data/sorted" \
  -v cornhole-cache:/data/.cornhole \
  uncompiled/cornhole:latest

Replace /path/to/your/videos and /path/to/your/sorted with the real folder paths from Step 2. On Windows, use a path like C:\Users\yourname\Videos\ToSort in place of the placeholder. Keep the quotes around the path.

Change only the paths on the left side of each :. The right side (/data/videos, /data/sorted) is the location inside the container, and Cornhole already looks there for your named folders, so leave it exactly as written.

If you did not create a "sorted" folder, remove the -v ".../sorted:/data/sorted" line. Cornhole works without it, but you will not have the move-to-folder option.

You do not need to create a .env file. The image already sets every setting it needs (the video folder, the sorted folder, the cache location, the database location, and port 3000).

If your terminal does not accept multi-line commands, remove the trailing \ characters and put the whole command on one line instead.

⁠Optional: match Cornhole to your own account

Cornhole runs inside Docker as its own user, separate from your own user account on your computer. By default this is not an administrator or a "root" account, so this step is safe to skip. But by default it is also not the same account as you. If you use the "sorted" folder from Step 2, files that Cornhole moves there will belong to Cornhole's own account, not yours. This can make those files hard to open, move, or delete from outside Cornhole later.

On Mac or Linux, you can tell Cornhole to use your own account instead. Add these two lines to the docker run command from Step 3, before the -v lines:

  -e PUID="$(id -u)" \
  -e PGID="$(id -g)" \

On Windows, file ownership works in a different way, and this step does not apply. Skip it.

⁠4. Open Cornhole

Go to http://localhost:3000⁠ in your browser, on the same computer.

To use Cornhole from your phone or another device on the same Wi-Fi network, use this computer's local network address instead of localhost (for example http://192.168.1.42:3000). To find this address, check your Mac or Windows network settings, or run ipconfig (Windows) or ifconfig (Mac or Linux) in a terminal.

The first launch takes time. Cornhole scans your whole video folder. Videos appear in the feed quickly, each with a rough thumbnail. After that, a background job works through the library again to refine each thumbnail to a better frame. A "Refining N thumbnails…" message under the header title tracks this second pass; you can start triaging before it finishes. For a few hundred videos, both passes take a few minutes. For several thousand videos, they take longer. This process occurs one time for each video. Cornhole skips videos it has already processed in later scans.

⁠5. Install Cornhole as an app (optional)

You can install Cornhole as an app (a PWA) on your phone or computer, which will install a convenient shortcut on your home screen or desktop.

• Android (Chrome): Tap the ⋮ menu. Select Install app (or Add to Home screen).
• iPhone/iPad (Safari): Tap the Share icon. Select Add to Home Screen. Note: iOS does not offer this option in Chrome. You must use Safari.
• Desktop (Chrome/Edge): Look for an install icon (⊕ or a small monitor icon) in the address bar.

This step is only for convenience. Cornhole works the same way as in a normal browser tab.

⁠How to use Cornhole

• One video at a time. Scroll to move through the feed. Tap a video to play it, starting from the moment shown in its thumbnail. Drag the scrub bar at the bottom of a playing video to jump to another part of it. Tap the sound icon to unmute the audio.
• Tag opens the tag picker. Type a new tag name and press Enter, or pick an existing tag from the list, to add it to the video. You can add more than one tag. Tap the × on a tag chip to remove it. Nothing is applied until you tap Done, which applies the whole set at once; the video stays where it is while you edit. Leaving the sheet without Done discards the staged set. A video with at least one tag moves to the Tagged tab; removing its last tag sends it back to Unsorted.
• Move opens a picker of your named Sorted subfolders (Step 2), and files the video straight into whichever one you pick, instead of only tagging it. Only appears if you set up a Sorted folder.
• Delete asks you to confirm. Then it removes the file immediately and permanently. There is no trash bin and no undo function.
• Unsorted / Tagged tabs, at the top of the feed, switch between videos still waiting on a decision and videos you've already tagged. The active tab shows a live count.
• Batch selection. Every card has a selection checkbox (hover it on a desktop browser). Select one or more videos to show a toolbar with Tag or Untag (depending on the tab), Move, and Delete, each acting on every selected video at once.
• The Tagged tab also shows a row of tag chips in the header, on the same row as the tabs. They stay visible while you scroll the feed. Tap a chip to select every currently loaded video with that tag, for quick batch actions (untag, move, or delete many videos at once). Tap it again to deselect them.
• Sort (the icon next to Settings) changes the feed's order: newest first (the default), longest or shortest first, or largest or smallest file size first.
• Card size, a slider in Settings on a desktop browser, scales the feed's grid between about four columns and a single column.
• Full-size view. On a desktop browser, hover a card and press Space to expand its video to fill the screen, with the browser's own play, pause, and volume controls. Press Space or Esc, or click outside the video, to close it. Press H any time to see this and the other keyboard shortcuts.
• New or removed files. Cornhole watches your video folder on its own. Adding or removing a file, or adding a new Sorted subfolder, shows up in Cornhole within a few seconds, with no restart or manual action needed.

⁠Things to know before you start

• Delete means delete. There is a confirmation step, but after you confirm, the file is deleted from the disk. It does not move the file to a trash bin. Do not use this app for a "maybe" pile.
• Cornhole is a tool for one person, not a shared inbox. It has no accounts and no login. If two people open the same Cornhole URL at the same time and both people swipe, one person's delete or tag action can remove a card while the other person views it. Do not share one instance between people.
• There is no login screen. This is intentional. Cornhole is built to run on your home network, which the app trusts by default. If you make Cornhole available outside your home network (through a VPN, a public URL, or port-forwarding on your router), any person with the link can delete your videos. If you only use Cornhole at home, you do not need to set up anything extra.
• Your videos stay on your computer. Cornhole does not upload any file. It only reads and writes the folders that you specify.
• The cache can grow in size. Cornhole creates a small thumbnail for each video. It stores these files separately from your original videos, in the cornhole-cache volume named in the command above. For a library with many thousand videos, this can add up to a noticeable amount of space, but far less than if Cornhole also stored a separate preview clip per video. This is not a large amount of space, but you should know it exists if your drive is small.
• Very old or unusual video files can show a poor thumbnail or not play. Cornhole reads frames with ffmpeg to pick a thumbnail, and your browser plays the original file directly. Both handle most phone and camera formats correctly. But an unusual codec on a very old file can create a thumbnail that looks wrong, or a video that will not play in the browser. The Tag and Delete functions still work in this case.

⁠Everyday commands

Stop Cornhole:

docker stop cornhole

Start Cornhole again (this keeps your data and progress):

docker start cornhole

Update to a newer version:

docker pull uncompiled/cornhole:latest
docker stop cornhole
docker rm cornhole

Then run the same docker run command from Step 3 again. Your tags and unsorted progress stay in the cornhole-cache volume. This volume survives the update.

Check the container status, or look for errors:

docker logs cornhole

Remove Cornhole completely, including its saved progress:

docker stop cornhole
docker rm cornhole
docker volume rm cornhole-cache

This does not affect your video files. It only removes Cornhole's own thumbnails, cache, and tag database. Your videos stay in the folder that you pointed the -v flag at, in every case.

⁠Troubleshooting

The feed shows "No videos found yet.", but I have videos in the folder. This is usually a folder-path problem or a permission problem, not a software fault:

• Check the path after -v in your docker run command. Confirm it points to the correct folder. A typing error is the most common cause.
• On Mac, confirm that the folder has permission under Docker Desktop's Settings → Resources → File Sharing.
• Run docker logs cornhole. Look for a line that starts with [scanner]. In this version, an unreadable video folder shows a clear message in this line, instead of failing without a message.
• Cornhole supports these file types: .mp4, .mov, .mkv, .webm, .avi. Cornhole skips other file types.

A message says sorting is disabled, or the move-to-folder option does not appear. The message names the cause. Match it to one of these:

• "the Sorted folder doesn't exist" — you did not mount a sorted folder in Step 3. Add the -v ".../sorted:/data/sorted" line, then restart with docker stop cornhole, docker rm cornhole, and the full docker run command from Step 3. This is the most common cause. A mounted folder cannot be added to a container that is already running, which is why this needs the full restart.
• "SORTED_ROOT is not set" — you passed -e SORTED_ROOT= (an empty value), which turns the move-to-folder option off on purpose. Remove that line to get it back.
• "SORTED_ROOT is inside your videos folder" — the two -v lines point at the same folder, or the sorted folder sits inside the video folder. Move the sorted folder somewhere outside your video folder and restart.

A message says "No folders found in Sorted". The folder is mounted correctly, but has no subfolders yet. Create at least one subfolder inside it, for example Sorted/Keep Forever. Cornhole picks it up on its own within a few seconds, no restart needed.

A video I moved to my "sorted" folder will not open, move, or delete on my own computer. This happens on Mac and Linux when Cornhole's account and your own account do not match. See "Optional: match Cornhole to your own account" in Step 3. After you add the PUID/PGID lines and restart Cornhole with docker stop cornhole, docker rm cornhole, and the updated docker run command, new moves will use your own account. Files moved before this change stay owned by Cornhole's old account; fix those with your computer's usual "change owner" tool, or move them again after the restart.

Port 3000 is already in use. I want to use a different port. Change the left side of -p 3000:3000 to any free port, for example -p 8080:3000. Then open http://localhost:8080 instead.

The first run is very slow. This is the initial scan (see Step 4). Check the progress bar. This process occurs one time for each video.

I use a Raspberry Pi or another ARM device, and Cornhole will not start, or it runs very slowly. Confirm that you pull uncompiled/cornhole:latest again (docker pull uncompiled/cornhole:latest), instead of using an old cached image. Recent versions publish images for both Intel/AMD and ARM devices.