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`.

If it cannot open device files, 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, it will first try to use `osascript` and will fall back to sending bell character. Enable `Audible bell` in Terminal --> Preferences --> Settings --> Advanced.

On Windows it uses Beep function via syscall.

On the Web it plays hard-coded beep sound.

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 will first try `terminal-notifier` 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
}