beeep

README

beeep

beeep provides a cross-platform library for sending desktop notifications, alerts and beeps.

Installation

go get -u github.com/gen2brain/beeep

Build tags

• nodbus - disable godbus/dbus and use only notify-send

Examples

err := beeep.Beep(beeep.DefaultFreq, beeep.DefaultDuration)
if err != nil {
    panic(err)
}

//go:embed testdata/info.png
var icon []byte

err := beeep.Notify("Title", "Message body", icon)
if err != nil {
    panic(err)
}

beeep.AppName = "My App Name"

err := beeep.Alert("Title", "Message body", "testdata/warning.png")
if err != nil {
    panic(err)
}

Documentation

Overview

Package beeep provides a cross-platform library for sending desktop notifications and beeps.

Index

• Constants
• Variables
• func Alert(title, message string, icon any) error
• func Beep(freq float64, duration int) error
• func Notify(title, message string, icon any) error

Examples

• Alert
• Beep
• Notify

Constants

const (
	// DefaultFreq - frequency, in Hz, middle A
	DefaultFreq = 440.0
	// DefaultDuration - duration in milliseconds
	DefaultDuration = 200
)

Constants

Variables

var AppName = "DefaultAppName"

AppName is the name of app. This should be the application's formal name, rather than some sort of ID.

var (
	// ErrUnsupported is returned when an operating system is not supported.
	ErrUnsupported = fmt.Errorf("beeep: unsupported operating system: %s", runtime.GOOS)
)

Functions

func Alert

func Alert(title, message string, icon any) error

Alert displays a desktop notification and plays a beep.

Example

package main

import (
	_ "embed"
	"github.com/gen2brain/beeep"
)

func main() {
	beeep.AppName = "My App Name" // change the default app name

	_ = beeep.Alert("Title", "MessageBody", "testdata/warning.png")
}

func Beep

func Beep(freq float64, duration int) error

Beep beeps the PC speaker (https://en.wikipedia.org/wiki/PC_speaker).

On Linux it needs permission to access `/dev/input/by-path/platform-pcspkr-event-spkr` file for writing, and `pcspkr` module must be loaded. User must be in the correct group, usually `input`. Without the PC speaker, the tone is played with `pw-play` or `paplay` when their sound server runs, else with `aplay`.

If none of these works, it will fall back to sending Bell character (https://en.wikipedia.org/wiki/Bell_character). For bell character in X11 terminals you can enable a bell with `xset b on`. For console check `setterm` and `--blength` or `--bfreq` options.

On macOS, this plays the system alert sound and will fall back to sending bell character.

On Windows it uses Beep function via syscall.

On the Web it plays the tone with the Web Audio API.

Example

package main

import (
	_ "embed"
	"github.com/gen2brain/beeep"
)

func main() {
	_ = beeep.Beep(beeep.DefaultFreq, beeep.DefaultDuration)
}

func Notify

func Notify(title, message string, icon any) error

Notify sends desktop notification. The icon can be string with a path to png file or png []byte data. Stock icon names can also be used where supported.

On Linux it tries to send notification via D-Bus, and it will fall back to `notify-send`.

On macOS, this uses the notification center (as Terminal outside of an app bundle) and will fall back to AppleScript with `osascript`.

On Windows 10/11 it will use Windows Runtime COM API and will fall back to PowerShell. Windows 7 will use win32 API.

On the Web it uses the Notification API, in Firefox it just works, in Chrome you must call it from some "user gesture" like `onclick`, and you must use TLS certificate, it doesn't work with plain http.

Example

package main

import (
	_ "embed"
	"github.com/gen2brain/beeep"
)

//go:embed testdata/info.png
var icon []byte

func main() {
	_ = beeep.Notify("Title", "MessageBody", icon) // icon is embedded file
}