Getting Started with VoiceLink

Getting Started

1. Get the app: on the VoiceLink download page, enter your email address. We email you links for Windows, Mac, iPhone and iPad, and the web app; pick the one for your device. The links work for 7 days and always open the newest version. Once installed, the app updates itself.
2. Open the app and allow microphone access if the system asks.
3. Choose a server such as Main or Community from the server list.
4. Move to the room list. Each room reads its name with separate counts of people and bots, for example "Classroom, 3 people, 4 bots". Open room details or join a room directly.
5. Confirm success by checking for room audio, the room title, users, bots, and system messages.

Choose the Right Install Path

Docker Server Install

For container hosts, create a persistent data directory and run VoiceLink behind your existing HTTPS reverse proxy. Build the image from the current server source, then replace https://your-server.example with the public URL you will register in VoiceLink.

git clone https://git.tappedin.fm/raywonder/voicelink.git
cd voicelink
docker build -t voicelink/server:local .
mkdir -p ~/voicelink-data
docker run -d \
  --name voicelink-server \
  --restart unless-stopped \
  -p 3010:3010 \
  -v "$HOME/voicelink-data:/app/data" \
  -e VOICELINK_PUBLIC_URL="https://your-server.example" \
  -e VOICELINK_HUB_URL="https://voicelink.dev" \
  voicelink/server:local

The container keeps its data in ~/voicelink-data. To upgrade, build the new image, then recreate the container with the same data directory; do not remove that directory.

Your Own Server: Rooms and Federation

Starter rooms

A new install creates only two rooms: Lobby and General. To add more, open Admin, then Modules, then Room templates. You can add one template or a whole pack, then edit the rooms as you like. See Room templates.

Upgrading an existing server

Existing servers keep all their rooms. Restarting the server never re-creates built-in rooms, and rooms you deleted stay deleted.

The old sample file server/data/rooms.json is no longer shipped with the server. Your own rooms file in your data directory is kept.

Listing your rooms in the federated directory

Your rooms are not shared with other servers until you allow it. To list them in the VoiceLink federated directory, open Admin, then Federation, and turn on "Listing enabled" under "Federated rooms listing". Then turn on "Show in federated rooms" for each room, or use "Show all public rooms in federated rooms". See Federated rooms listing.

Main Navigation

• Tab one is Servers. Use it to search, browse server owners, open an owner button, and choose a specific server.
• Tab two is Federated Rooms. It is one flat list of rooms from this server and connected servers, with a search field and filters for category, type and server. Press Enter on a room's Join button to join it. See Federated Rooms.
• Tab three is Settings. It lists the settings categories; each one opens its own screen. See iPhone Settings below.
• The server list is grouped by server owner, then by server display name. Each owner appears as a button that shows the number of servers that owner runs, such as Devine Creations (2 servers). Open that button to show the servers behind it.
• Server owners can configure the owner name, public display name, and display mode from the server administration settings. Those values are used by desktop, iOS, federation search, and public server discovery.
• The selected server's room list opens after you choose a server from the Servers tab. Federated Rooms remains a separate tab for cross-server browsing.
• On iPhone and iPad, each step opens its own screen: the Servers tab lists server owners (for example VoiceLink, 3 servers); choosing one opens a screen of that owner's servers (an owner with one server opens that server straight away); choosing a server opens its screen with its rooms first (people and agent counts), then that server's actions such as Sign In to This Server and Administration, then details about it. Addresses are not shown. The Back button, or Escape on a keyboard, goes back one screen, and VoiceOver returns to the row you came from.
• On iPhone and iPad the room lists refresh by themselves while you look at them (about every 30 seconds, less often when nothing changes) and when you come back to the app. You can still pull down to refresh (with VoiceOver, swipe down with three fingers); VoiceLink says "Updated". If a server is restarting, its rooms stay listed and it is retried quietly.
• VoiceOver hints tell you what a double-tap does: "Double-tap to join" on a room, "Double-tap to open" on a server or server group. To make a double-tap preview a room, show its details or share it instead, go to Settings, General, Double-Tapping a Room. The other room actions are in the Actions rotor (swipe up or down) and the touch-and-hold menu.
• In the web app, the Servers tab lists servers by name and status only, for example Main, online, 12 people, 20 rooms. Press Enter on a server to open its own screen: its name as a heading, then its rooms (each with people and agent counts and a Join button), then that server's actions. Press Escape, the browser Back button or Alt+Left (Command+Left Bracket in Safari on the Mac) to return to the server list; focus goes back to the server you came from. Joining a room on another server opens that server's web app with the room ready to join.
• Room details tell you the server name, room name, access level, and current media state.
• Settings stays available while you are in a room so you can change diagnostics, audio, or announcement preferences without leaving.

Service Notices

When a server admin posts a maintenance, outage or information notice, the web app shows it as a popup you can dismiss; dismissing it is remembered on that device (or account, if you're signed in), so it won't pop up again. A Service notices button next to Sign In shows how many active notices you haven't dismissed yet, and opens a list of current and recently-ended notices. Screen readers announce a new notice when it appears. Server admins manage notices from Admin, Service Notices, on the main server; community and dev servers show the same notices automatically.

A notice with a start or end time shows a countdown next to it, such as "Starts in 1 day, 3 hours and 12 minutes" or "Ends in 2 hours and 5 minutes" (or, for a notice starting tomorrow, "Starts tomorrow at 9 AM your time"); it disappears once the notice ends. The countdown text updates quietly, at most once a minute, and doesn't interrupt your screen reader, but reading or tabbing to it always announces the exact current countdown. You'll also hear a one-time spoken heads-up 1 hour before, 10 minutes before, and when a notice starts or finishes, as long as desktop notifications are turned on.

iPhone Settings

Settings on iPhone and iPad work like the desktop VoiceLink app. The main Settings screen has no switches of its own: it is a list of categories, each with a short line saying what is inside. Double tap a category to open its screen. At the top of each screen, a row of tabs switches between groups of settings; VoiceOver reads it as, for example, "Security tabs", and says the tab name when you change it.

• General: Startup (Allow My Voice in Room Preview) and Help and Policies (docs, support and download links).
• Profile & Authentication: User Information (who you are signed in as) and Authentication (sign in, other sign-in methods, sign out).
• Security: Account Security (your signed-in devices, with Remove for a lost device) and Two-Factor Status.
• Accessibility: Speech (what is read aloud in rooms, and the voice) and VoiceOver tips.
• Audio: Audio Controls (mute media, input and output levels up to 300 percent, Test Sound).
• Sync & Filters: Room Visibility (show user statuses in room lists) and Contacts (sync VoiceLink contacts).
• Notifications: Push Notifications and Sound Notifications.
• Privacy: Data (automatic diagnostics and crash reports, privacy policy and privacy choices).
• Advanced: Developer Options, Diagnostics Submission Log (send a report, see recent ones) and Feedback and Community.

Settings that depend on the server

The last row of Settings belongs to the server you are connected to and changes when you switch servers, sign in or out, or your role changes. The footer says which server it is and your role there.

• Admin appears if you have any management permission on that server. Its tabs show only what you are allowed to do: Overview (your access and the server's status), Users (people online, moderation and bans), Rooms (create, edit, lock and delete rooms) and Server Config (server name, message of the day, rules, web management and backups).
• Web client (browser): Enabled is a per-server owner/admin setting in the web app's own Admin panel (Server tab). Turning it off shows an accessible plain page to anyone reaching this server's browser sign-in or chat page and points them to the desktop or mobile app instead; it does not affect the VoiceLink desktop or mobile apps or their own sign-in. This setting only lives in the web Admin panel for now, so turn it back on the same way: open that server's Admin panel in a browser (Windows' Admin button opens this in your default browser too). Each server (main, community, dev) keeps its own independent setting.
• My Rooms appears if you are signed in without admin rights. It lists the rooms you created on that server. Where the server allows it, such as the community server, you can rename and lock them; otherwise you see their details and can still moderate people from the room actions while in the room.
• As a guest, the last row is Sign in to manage rooms, which opens sign in for that server.

Working with Rooms

Preview a room

Use Preview when you want to hear a short sample of room media before joining. The preview ends on its own after the short preview window.

Open room details

Open room details when you need the room description, server source, visibility, access level, or the list of available actions before joining. Room details also say when the room was last active and who was there, for example "Last active: 5 minutes ago by Dom", and list up to three people recently in the room. For private or password rooms, only members, room managers and server admins see the names; everyone else hears just the time. A room with no activity on record says "No recent activity".

Choose the correct server owner

When multiple organizations host servers, browse by owner button first. For example, the VoiceLink owner group can contain the Main and Community servers, while Devine Creations can contain its devine-creations.com and devinecreations.net servers. The number beside the owner tells you how many servers are currently listed for that owner. Open the owner button, then choose the server you want.

Join a room

Join the room from the room row or details view. After joining, the room header and user list should update to reflect the active room.

Staying signed in

Sign in once and VoiceLink keeps you signed in on that server. The apps renew your sign-in quietly in the background, including after the server restarts or updates, for both VoiceLink accounts and Client Portal accounts. On iPhone and iPad the sign-in is kept in the device Keychain.

An account from the main VoiceLink server is also recognised on the community and dev servers. Your role there (for example admin or moderator) is set separately on each server and never carries over.

If a sign-in really can't be renewed (for example after you signed out on another device), you are never stopped from joining: you join as a guest, VoiceOver tells you once that your sign-in expired, and a Sign in again button appears at the top of the app. Double tap it to sign in, or dismiss it.

Talking as a guest

You don't need to sign in to talk. After joining a room, the microphone switch works for guests too. The first time, the iPhone app explains why it needs the microphone, then iOS asks for permission. If microphone access is off, VoiceOver tells you how to turn it on: open the Settings app, choose VoiceLink, and turn on Microphone.

A room manager can set a room so that only signed-in people can talk (the room setting guestsCanTalk; it is on by default). Guests in that room can still listen and chat, and hear "In this room only signed-in people can talk". A moderator can also mute one person's microphone; that person can't unmute themselves.

Review people and messages

After joining, move to the user list and message area to confirm users, bots, room chat, and system messages. If the room is configured to show chat, messages should appear above the message box. The room also shows how many people and bots are in it, for example "In this room: 3 people, 4 bots". These counts change by themselves as people and bots join or leave.

Photos and files in chat

Room chat and direct messages can include a photo or a file sent from the VoiceLink apps. In the web client:

• A photo shows as an image. Activate it to open it full size in a new tab.
• Any other file shows as a link that starts with "File:" and the file name.

Uploading a photo or file needs you to be signed in to that server.

Adjust audio controls

Use the room menu or user actions to show audio controls only when needed. Volume, mute, monitoring, and media choices should remain available without forcing you out of the room.

VoiceOver and Keyboard Notes

• VO-Space activates the selected control.
• VoiceOver actions on a room row can expose actions such as Preview, Join, Share, or Details.
• Sliders should announce percentage values and adjust in consistent steps.
• Use the room menu instead of leaving and rejoining when you only need settings or audio changes.

Welcome Chime

VoiceLink plays a short welcome chime once when it opens. In a web browser, the browser may hold the sound until your first key press or click; it plays then. To turn it off in the web app, open Settings and clear "Play the welcome chime when VoiceLink opens". On the Mac, it is "Play startup welcome sound" in Settings, Audio Controls.

Sound Notifications

VoiceLink plays a short sound for things like joining or leaving a room, someone else joining or leaving while you're in it, messages, mute and push-to-talk, whisper, and connecting, losing the connection or reconnecting to a server. On iPhone/iPad, these are in Settings, Notifications, Sound Notifications: "Play Sound for System Action Notifications" turns them on or off, "Play sounds when the silent switch is on" controls whether they respect the iPhone's silent switch (on by default, since you're actively using the app), and a Sound Volume slider sets how loud they play without affecting room audio.

Update and Error Reports

Update and error reports. To help us fix problems quickly, VoiceLink tells our server when an update installs, fails or doesn't reopen, and when the app hits an error. A report contains a random install number (not linked to your account), the app version, your operating system version and a short error description. It never includes your messages, contacts, files, passwords, keys or user name. You can turn this off in Settings, under "Send update results and error reports". Diagnostic logs are only sent when you choose Help, Send diagnostic logs.

• Mac: the switch is in Settings, Privacy. Send logs with Help, Send Diagnostic Logs; you can type what happened, and VoiceLink shows a reference number to mention to support.
• iPhone and iPad: the switch is in Settings, Privacy. Send logs from Settings, Advanced, Diagnostics Submission Log, Send Diagnostic Logs.
• Windows: the check box is in File, Settings, Privacy. Send logs with Help, Send diagnostic logs.
• Web app: the check box is in Settings, Privacy. The web app only reports errors, never what you type or say.
• If an update can't download because you're offline or the network is having trouble, VoiceLink doesn't show an error. It tries again quietly a few minutes later, and again when your connection comes back.

Troubleshooting

Contact and Feedback

If your first room join does not match this guide, send a bug report from Settings and include the build number, server name, room name, and the last action you took before the problem started.