ShowShark Watch Parties: Synchronized Viewing with Friends & Family

Watch Parties let you watch movies and episodes from your ShowShark library in sync with other people, regardless of where they are. One person hosts; everyone else joins with a short invite code. The server handles all the synchronization; participants just sit back and watch.

This tutorial covers the full lifecycle: setting up admin access, creating a party, inviting guests, managing a party in progress, and the server-side controls available to the library owner.

How It Works

                          +-------------------------+
                          |   ShowShark Server      |
                          |                         |
                          |  1. Host creates party  |
                          |  2. Server generates    |
                          |     invite code         |
                          |  3. Registers invite    |
                          |     with cloud relay    |
                          +-----------+-------------+
                                      |
                     +----------------+----------------+
                     |                                 |
              +------v--------+                  +------v--------+
              |  Cloud Relay  |                  |  Cloud Relay  |
              | (invite code  |                  | (web page +   |
              |  stored here) |                  |  deep link)   |
              +------+--------+                  +------+--------+
                     |                                  |
          +----------+----------+           +----------+---------+
          |                     |           |                    |
   +------v------+       +------v-----+   +-v----------+  +------v-----+
   | Guest App   |       | Guest App  |   | Guest App  |  | Guest      |
   | (deep link) |       | (tvOS code |   | (web link) |  | (browses   |
   |             |       |  entry)    |   |            |  |  to URL)   |
   +------+------+       +-----+------+   +-----+------+  +-----+------+
          |                    |                |               |
          +----------+---------+----------------+               |
                     |                                          |
              +------v--------+                           +-----v--------+
              |   Lobby       |                           |  Web Page    |
              |               |                           |  "Open in    |
              | - Countdown   |                           |   ShowShark" |
              | - Lineup      |  <------------------------+  deep link   |
              | - Members     |    (taps button,          +--------------+
              +------+--------+     opens app)
                     |
              +------v---------+
              |   Live         |
              |   Playback     |
              |                |
              | - Synchronized |
              | - Auto-advance |
              +------+---------+
                     |
              +------v---------+
              |   Ended        |
              |                |
              | - Post-party   |
              |   message      |
              +----------------+

Prerequisites

• ShowShark Server running on your Mac.
• A video playlist with at least one item. Watch Parties are built on top of playlists; the playlist becomes the viewing lineup.
• Admin access on the device creating the party (more on this below).
• Remote connectivity (the Upgrade tab in the server) if any guest is outside your local network. Guests on the same LAN can join without it.

Step 1: Ensure Your Device Has Admin Access

Only admin devices can create and manage Watch Parties. There are two ways a device becomes an admin:

Automatic (first device): The very first device to connect to your server is granted admin status automatically. If you set up your server and immediately connected from your iPhone, that iPhone is already an admin.

Manual (subsequent devices): Open ShowShark Server on your Mac. Navigate to the Devices tab in the sidebar. Find the device you want to promote, hover over its row, and click the pencil icon to open the editor. In the Role section, toggle Administrator on, then click Save. Reconnect that device to ShowShark Server.

An admin device sees additional controls throughout the client app: the Watch Party button on playlists, host controls in the lobby, and management options for active parties.

Step 2: Create a Video Playlist

Watch Parties play through a playlist from start to finish, in order. Before creating a party, build the playlist you want everyone to watch.

1. Open the ShowShark client on your admin device.
2. Navigate to a movie or episode detail view.
3. Add it to a playlist (or create a new one).
4. Repeat for every title you want in the lineup.

The playlist must be a video playlist. Music playlists do not support Watch Parties (as the name implies?).

Step 3: Create the Watch Party

Open your video playlist in the client app. In the toolbar (iOS, macOS, visionOS) or the button bar (tvOS), you will see a button with a party popper icon. Tap it to open the creation form.

Fill in the details:

Tap Create. The server generates an 8-character invite code and a shareable URL. You are taken to the invite screen.

Step 4: Share the Invite

The invite screen displays two things:

• An 8-character code in large monospaced text. This is what guests enter if they are on Apple TV or prefer manual entry.
• A shareable URL that opens a web page with party details and a deep link into the app.

On iOS, macOS, and visionOS, tap Share Invite to open the system share sheet. Send the link via Messages, email, AirDrop, or any other channel. On tvOS, read the code aloud or send it from another device.

The invite code is valid until the party ends or is cancelled.

Step 5: Guests Join the Party

Guests have three ways to join, depending on platform and preference.

Option A: Tap the Link (iOS, macOS, visionOS)

The guest taps the shared URL. A web page opens showing the party name, host server, scheduled start time, and the content lineup. A prominent Open in ShowShark button deep-links into the app. If ShowShark is not installed, the page falls back to the App Store.

When the app opens, it silently looks up the invite code, connects to the host server (joining the tailnet if needed), and drops the guest directly into the party lobby. No manual server configuration is required.

Option B: Enter the Code (tvOS)

On Apple TV, the guest opens ShowShark and navigates to the Channels tab. A Join Watch Party button opens a code entry screen. The guest enters the 8-character code using the Siri Remote and taps Join. The app handles the rest identically to Option A.

Option C: Browse to the URL

If the guest does not have the app installed yet, they can open the invite URL in a browser. The web page displays the party details and invite code. After installing ShowShark from the App Store, the guest can enter the code manually (tvOS) or tap the deep link button on the web page.

The Lobby

Once a guest joins, they land in the lobby. The lobby shows:

• A countdown timer ticking down to the scheduled start time.
• The content lineup with thumbnails, titles, and durations for every item in the playlist.
• A member list showing the names of all connected devices.
• The pre-party message, if the host set one.

The lobby polls the server every few seconds. When the host starts the party (or the scheduled time arrives), everyone transitions to playback automatically.

Host Controls in the Lobby

If you are the host (the admin who created the party), you see two additional buttons:

• Start Now begins playback immediately, regardless of the countdown. Use this when everyone has arrived early.
• Cancel Party terminates the party and notifies all guests. A confirmation dialog prevents accidental cancellation.

During Playback

Playback is fully synchronized. The server decodes the video once and streams it to all participants. Items play in playlist order and advance automatically. There is nothing for guests to do except watch.

When the last item in the playlist finishes, the server transitions the party to the Ended state. Guests see the post-party message (if one was set) and a Done button to return to the app.

Managing an Active Watch Party (Client)

If you navigate back to the source playlist while a party is active, the toolbar button changes from "Create Watch Party" to Manage Watch Party. Tapping it opens the management sheet.

While the party is still scheduled or in the lobby, you can edit:

• Party name
• Scheduled start time
• Pre-party message
• Post-party message

The invite code is displayed (read-only) with a Copy button that copies a pre-formatted message including the code and URL.

You can also Cancel Party from this sheet, which immediately cancels and notifies all participants.

Once the party is live, the sheet becomes read-only. The party name, status, and invite code are displayed, but no fields are editable. You can still cancel a live party if needed.

Managing Watch Parties (Server App)

The ShowShark Server app on your Mac provides a bird's-eye view of all Watch Parties, past and present.

Open the Channels tab in the server sidebar. A Watch Parties section appears at the top, above your TV channels. Each party row shows:

• The party name and current status (color-coded: blue for scheduled, orange for lobby, green for live, gray for ended or cancelled).
• The scheduled start time.
• The member count.
• The invite code (click to copy the full share text to your clipboard).

Click a watch party row to open its editor. From here you can update the party details, manually start it, or cancel it; the same options available in the client, but accessible from the server without needing an admin device in hand.

The server automatically cleans up ended and cancelled parties after 24 hours.

Troubleshooting

"Create Watch Party" button does not appear.
Your device is not an admin. Ask the server owner to toggle Administrator on for your device in the Devices tab.

Guest cannot join with the invite code.
Verify remote connectivity is active (Status tab in the server shows a tailnet interface). If the guest is on the same local network, remote connectivity is not required; but the server must still be running and reachable.

Lobby shows "Starting soon..." but playback does not begin.
The server transitions to live when the scheduled time arrives. If the countdown reaches zero and nothing happens, check that the server app is still running. The host can also tap Start Now to force it.

Party ended unexpectedly.
If the server restarts or the playlist is empty, the party may transition to ended prematurely. Ensure the playlist has items and the server stays running for the duration of the party.