Table of Contents Previous entry (api:GM_cookie.delete) Next entry (api:window.onurlchange)

GM_audio.setMute(details, callback?)

Sets the mute state of the current tab.

Parameters

• details object, describing the new mute state of the tab:
  • isMuted boolean, true to mute the tab, false to un‑mute it.
• callback (optional) function?, called when the operation finishes.
  • error (optional) string, contains an error message if setting the mute state fails, otherwise it is undefined.

Return value

• Callback style: nothing (result is delivered via the callback).
• Promise style: returns a Promise<void> that resolves on success and rejects with an error string on failure.

Example (callback)

// ==UserScript==
...
// @grant      GM_audio
// ==/UserScript==

GM_audio.setMute({ isMuted: true }, function(err) {
  if (err) console.error('mute failed:', err);
  else console.log('tab muted');
});

Example (Promise)

// ==UserScript==
...
// @grant      GM.audio
// ==/UserScript==

await GM.audio.setMute({ isMuted: false });
console.log('tab un‑muted');

GM_audio.getState(callback)

Retrieves the current audio state of the tab.

Parameters

• callback function, to be called with an object describing the tab’s audio state:
  • info object, representing the retrieved state
    • isMuted (optional) boolean, whether the tab is currently muted.
    • muteReason (optional) string, the reason why the tab was muted, if it is currently muted.
      • user – User action (e.g., mute button).
      • capture – Tab capture API call.
      • extension – Extension call.
    • isAudible (optional) boolean, whether the tab is currently playing audio.

Return value

• Callback style: nothing (state delivered via the callback).
• Promise style: returns a Promise that resolves with the callback’s info object on success or rejects on error.

Example (callback)

// ==UserScript==
...
// @grant      GM_audio
// ==/UserScript==

GM_audio.getState(function(state) {
  if (!state) return console.error('failed to read state');
  console.log('muted?', state.isMuted, 'reason:', state.muteReason);
  console.log('audible?', state.isAudible);
});

Example (Promise)

// ==UserScript==
...
// @grant      GM.audio
// ==/UserScript==

const state = await GM.audio.getState();
console.log(`muted=${state.isMuted} (reason=${state.muteReason}) audible=${state.isAudible}`);

GM_audio.addStateChangeListener(listener, callback)

Registers a listener that is called whenever the tab’s mute or audible state changes.

Parameters

• listener function, to be called when state changes. The function will be passed one argument:
  • info object, representing the retrieved state change
    • muted (optional) string | false, mute reason or false if not muted.
    • audible (optional) boolean, whether the tab is currently playing audio.
• callback (optional) function?, called once the registration attempt is complete. The function will be passed one argument:
  • error (optional) string?, containing an error message if registration fails, or undefined otherwise.

Return value

• Callback style: nothing (listener registered via callback).
• Promise style: returns a Promise<void> that resolves when the listener has been successfully registered.

Example (callback)

// ==UserScript==
...
// @grant      GM_audio
// ==/UserScript==

GM_audio.addStateChangeListener(function(e) {
  if ('muted' in e) console.log('muted:', e.muted);
  if ('audible' in e) console.log('audible:', e.audible);
});

Example (Promise)

// ==UserScript==
...
// @grant      GM.audio
// ==/UserScript==

await GM.audio.addStateChangeListener(ev => {
  if (ev.muted) console.log('muted by', ev.muted);
});

GM_audio.removeStateChangeListener(listener, callback)

Unregisters a previously added state‑change listener.

Parameters

• listener function, The exact listener function that was passed to addStateChangeListener:
• callback (optional) function?, called once the listener has been removed

Return value

• Callback style: nothing.
• Promise style: returns a Promise<void> that resolves when the listener has been removed.

Example (callback)

// ==UserScript==
...
// @grant      GM_audio
// ==/UserScript==

function onAudio(ev) { console.log(ev); }
GM_audio.addStateChangeListener(onAudio);
...
GM_audio.removeStateChangeListener(onAudio, () => console.log('listener removed'));

Example (Promise)

// ==UserScript==
...
// @grant      GM.audio
// ==/UserScript==

await GM.audio.removeStateChangeListener(onAudio);
console.log('listener removed');