SSH Connection Sound

A cross-platform VS Code extension that plays sounds for Remote-SSH connection success, failure testing, and disconnect events.

The extension runs as a UI extension, so sound playback happens on your local computer rather than on the remote SSH server.

Features

Remote-SSH connection success sound
Remote-SSH disconnect sound
Success sound test command
Failure sound test command
Disconnect sound test command
Reload sounds configuration without restarting VS Code
Windows support
macOS support
Linux support
Custom sound configuration
Native operating-system sound support
Multiple Linux playback backends
Configurable polling interval
No external runtime npm dependencies
Runs locally when using Remote-SSH

Download

Latest VSIX

Download the latest .vsix package from the GitHub Releases page.

The release assets contain the installable VS Code extension:

ssh-connection-sound-X.Y.Z.vsix

Installation

Option 1 — Install the VSIX from the terminal

After downloading the .vsix file:

code --install-extension ssh-connection-sound-0.0.3.vsix

Option 2 — Install from VS Code

Open VS Code.
Open the Extensions view.
Click the ... menu.
Select Install from VSIX...
Select the downloaded .vsix file.
Reload VS Code if requested.

Supported Operating Systems

Windows

Supported:

Windows 10
Windows 11

Windows uses native .NET SystemSounds for configured system sounds.

Custom sound files can also be configured as .wav files.

macOS

macOS uses the built-in:

afplay

System sound files can be configured using .aiff files.

Linux

The extension supports common Linux audio playback utilities:

paplay
aplay
ffplay
canberra-gtk-play

It also checks several common locations for desktop notification sounds.

Supported distributions include:

Ubuntu
Debian
Fedora
Arch Linux
Other Linux distributions with a supported audio playback utility

How It Works

The extension monitors the VS Code remote environment:

vscode.env.remoteName;

When VS Code enters a Remote-SSH environment, the extension detects the SSH connection and plays the configured success sound.

When the Remote-SSH environment disappears, the extension detects the disconnect and plays the configured disconnect sound.

The extension is configured as a UI extension:

"extensionKind": [
  "ui"
]

This is important because the extension needs to play audio through the local computer's audio system.

The remote SSH server does not need to have the sound files or audio playback utilities installed.

Sound Configuration

Sound configuration is stored in:

sounds.json

The bundled configuration contains platform-specific sounds.

Example structure:

{
    "windows": {
        "success": {
            "type": "system",
            "sound": "Asterisk"
        },
        "failure": {
            "type": "system",
            "sound": "Hand"
        },
        "disconnect": {
            "type": "system",
            "sound": "Exclamation"
        }
    },

    "macos": {
        "success": {
            "type": "file",
            "path": "/System/Library/Sounds/Glass.aiff"
        },
        "failure": {
            "type": "file",
            "path": "/System/Library/Sounds/Basso.aiff"
        },
        "disconnect": {
            "type": "file",
            "path": "/System/Library/Sounds/Submarine.aiff"
        }
    },

    "linux": {
        "success": {
            "type": "file",
            "paths": [
                "/usr/share/sounds/freedesktop/stereo/complete.oga",
                "/usr/share/sounds/freedesktop/stereo/message-new-instant.oga",
                "/usr/share/sounds/freedesktop/stereo/dialog-information.oga"
            ]
        },
        "failure": {
            "type": "file",
            "paths": [
                "/usr/share/sounds/freedesktop/stereo/dialog-error.oga",
                "/usr/share/sounds/freedesktop/stereo/dialog-warning.oga"
            ]
        },
        "disconnect": {
            "type": "file",
            "paths": [
                "/usr/share/sounds/freedesktop/stereo/service-logout.oga",
                "/usr/share/sounds/freedesktop/stereo/device-removed.oga"
            ]
        }
    }
}

Custom Sounds

You can provide your own sounds.json file.

In VS Code settings, configure:

SSH Connection Sound: Sounds File

or use:

{
    "sshConnectionSound.soundsFile": "/path/to/your/sounds.json"
}

The extension also supports:

~/path/to/sounds.json

and relative paths.

After changing the file, use:

SSH Connection Sound: Reload Sounds

to reload the configuration.

VS Code Settings

The extension provides the following settings.

Enable or Disable Sounds

Setting:

sshConnectionSound.enabled

Default:

true

Example:

{
    "sshConnectionSound.enabled": true
}

Custom Sounds File

Setting:

sshConnectionSound.soundsFile

Default:

""

An empty value uses the bundled sounds.json.

Example:

{
    "sshConnectionSound.soundsFile": "/home/user/.config/ssh-sounds.json"
}

Polling Interval

Setting:

sshConnectionSound.pollInterval

Default:

The value is specified in milliseconds.

Example:

{
    "sshConnectionSound.pollInterval": 500
}

The minimum supported value is:

100 ms

Commands

Open the VS Code Command Palette:

Ctrl+Shift+P

or on macOS:

Cmd+Shift+P

Available commands:

Test Success Sound

SSH Connection Sound: Test Success Sound

Immediately tests the configured success sound.

Test Failure Sound

SSH Connection Sound: Test Failure Sound

Immediately tests the configured failure sound.

Test Disconnect Sound

SSH Connection Sound: Test Disconnect Sound

Immediately tests the configured disconnect sound.

Reload Sounds

SSH Connection Sound: Reload Sounds

Reloads the configured sounds.json file.

This allows sound configuration changes without restarting VS Code.

Remote-SSH Usage

Install the extension on your local VS Code installation.

Then connect to a remote machine using:

Remote-SSH: Connect to Host...

The extension runs locally and monitors the VS Code remote environment.

Example:

Local Computer
│
├── VS Code
│   └── SSH Connection Sound
│
└── Audio Output
    └── Speakers / Headphones
            │
            │
            ▼
       Remote SSH Server

The audio is played locally.

You do not need to install this extension separately on the remote server.

Failure Detection

VS Code's public extension API does not expose the complete internal Remote-SSH connection log stream.

Therefore, the extension can reliably detect:

Remote-SSH connection success
Remote-SSH disconnect

The failure sound is available through the test command.

Automatic detection of every possible Remote-SSH failure is not guaranteed because Remote-SSH's internal connection logs are not exposed as a stable public VS Code API.

Development

Clone the repository:

git clone https://github.com/omarZACK/vscode-ssh-connection-sound.git
cd vscode-ssh-connection-sound

Install the VS Code Extension Manager:

npm install -g @vscode/vsce

Package the extension:

vsce package

This generates:

ssh-connection-sound-X.Y.Z.vsix

Install the local package:

code --install-extension ./ssh-connection-sound-X.Y.Z.vsix

Project Structure

vscode-ssh-connection-sound/
│
├── .github/
│   └── workflows/
│       ├── ci.yml
│       └── release.yml
│
├── extension.js
├── sounds.json
├── package.json
├── README.md
├── LICENSE
├── .gitignore
└── .vscodeignore

GitHub Actions

The repository uses GitHub Actions for automated validation and releases.

Continuous Integration

The CI workflow validates:

package.json
sounds.json
extension.js
VSIX packaging

It runs on pushes to main and pull requests targeting main.

Releases

A release is created automatically when a version tag is pushed:

v0.0.3
v0.0.4
v0.1.0
...

The release workflow:

Checks out the repository.
Installs Node.js.
Installs vsce.
Verifies that the Git tag matches package.json.
Builds the .vsix.
Creates a GitHub Release.
Uploads the .vsix as a release asset.
Generates GitHub release notes.

Creating a Release

Update the version in:

package.json

For example:

"version": "0.0.4"

Commit the change:

git add package.json
git commit -m "chore: bump version to 0.0.4"
git push origin main

Create the Git tag:

git tag v0.0.4
git push origin v0.0.4

GitHub Actions will automatically build and publish:

ssh-connection-sound-0.0.4.vsix

Manual Packaging

You can always build the VSIX locally:

vsce package

Inspect the files included in the package:

vsce ls

Install the generated package:

code --install-extension ./ssh-connection-sound-0.0.3.vsix

License

This project is licensed under the MIT License.

See LICENSE for details.

Repository

GitHub:

https://github.com/omarZACK/vscode-ssh-connection-sound

Releases:

https://github.com/omarZACK/vscode-ssh-connection-sound/releases

Latest release:

https://github.com/omarZACK/vscode-ssh-connection-sound/releases/latest

Author

Omar Wawy

GitHub:

https://github.com/omarZACK