Skip to main content

SoundPlayback

This was deprecated in v1.0.0
Part of the deprecated SoundPool package; no longer maintained.

A handle to one sound started by SoundPool:PlaySound. It wraps the borrowed Sound instance, lets you pause / resume / stop it or change its config while it plays, and returns the pooled part to the pool with Return. When the sound ends on its own (Sound.Ended) it is returned automatically. After Return, using the handle in any way errors with "Sound has already been returned.". 

local playback = pool:PlaySound(1234567890)
playback:UpdateConfig({ Volume = 0.3, Position = character.HumanoidRootPart.Position })

playback.Ended:Connect(function()
	print("done") -- the pooled sound has already been returned at this point
end)

task.wait(1)
playback:Stop()
playback:Return() -- Stop does not fire Ended, so return it yourself

This package is no longer maintained; see the deprecation notice on SoundPool.

Properties​

Trove​

</>
SoundPlayback.Trove: Trove

Holds the wrapped signals below. It is not cleaned by Return; clean it yourself if you keep the handle around.

SoundInstance​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.SoundInstance: Sound

The pooled Sound that is playing. Read its properties (e.g. TimePosition) here; prefer UpdateConfig for writing.

PooledSound​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.PooledSound: PooledSound

The borrowed Part the Sound is parented to; move it to move the sound in 3D.

Returned​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.Returned: boolean

true once the pooled sound has been given back to the pool.

Ended​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.Ended: Signal<string>

Wraps Sound.Ended: fires with the sound id when playback finishes naturally. The pool has already returned the sound when your connection runs.

Stopped​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.Stopped: Signal<string>

Wraps Sound.Stopped: fires with the sound id after Stop.

Paused​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.Paused: Signal<string>

Wraps Sound.Paused: fires with the sound id after Pause.

Resumed​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.Resumed: Signal<string>

Wraps Sound.Resumed: fires with the sound id after Resume.

DidLoop​

This item is read only and cannot be modified. Read Only
</>
SoundPlayback.DidLoop: Signal<string,number>

Wraps Sound.DidLoop: fires with the sound id and the loop count each time a looped sound restarts.

Functions​

UpdateConfig​

</>
SoundPlayback:UpdateConfig(
soundConfig: SoundConfig--

The properties to change.

) → ()

Applies the fields set in soundConfig to the playing Sound (and Position to the pooled Part) immediately. Fields left nil are not touched. This is currently the only way to configure a sound, since PlaySound ignores its config argument.

Pause​

</>
SoundPlayback:Pause() → ()

Pauses the Sound (Sound:Pause()), keeping its TimePosition. Fires Paused.

Resume​

</>
SoundPlayback:Resume() → ()

Resumes a paused Sound from where it stopped (Sound:Resume()). Fires Resumed.

Stop​

</>
SoundPlayback:Stop() → ()

Stops the Sound (Sound:Stop()) and resets its TimePosition. Fires Stopped, not Ended, so the pooled sound is not returned automatically; call Return when you are done with it.

Return​

</>
SoundPlayback:Return() → ()

Gives the pooled Part back to the SoundPool so it can be reused, and marks the handle as returned. It does not stop the Sound first, so call Stop before Return if it is still playing. Called automatically when the sound Ended. After this, indexing the handle (any property or method) errors, so drop your reference.

Errors

TypeDescription
"Sound has already been returned."Called a second time on the same playback.
Show raw api
{
    "functions": [
        {
            "name": "new",
            "desc": "Wraps a borrowed pooled sound, connects the Sound's events as Signals, arranges for `Return` to\nbe called when `Ended` fires, and starts playback with `Sound:Play()`. Created by\n`SoundPool:PlaySound`; not meant to be called directly. The `soundConfig` argument is stored\nnowhere and not applied.",
            "params": [
                {
                    "name": "pooledSound",
                    "desc": "The borrowed Part.",
                    "lua_type": "PooledSound"
                },
                {
                    "name": "soundInstance",
                    "desc": "The Sound inside that Part, with `SoundId` already set.",
                    "lua_type": "Sound"
                },
                {
                    "name": "soundConfig",
                    "desc": "Accepted but unused in this version.",
                    "lua_type": "SoundConfig?"
                },
                {
                    "name": "returnCallback",
                    "desc": "Called once by `Return` to give the Part back to the pool.",
                    "lua_type": "() -> ()"
                }
            ],
            "returns": [
                {
                    "desc": "The playing handle.",
                    "lua_type": "SoundPlayback"
                }
            ],
            "function_type": "static",
            "private": true,
            "source": {
                "line": 276,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "UpdateConfig",
            "desc": "Applies the fields set in `soundConfig` to the playing Sound (and `Position` to the pooled\nPart) immediately. Fields left `nil` are not touched. This is currently the only way to\nconfigure a sound, since `PlaySound` ignores its config argument.",
            "params": [
                {
                    "name": "soundConfig",
                    "desc": "The properties to change.",
                    "lua_type": "SoundConfig"
                }
            ],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 323,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Pause",
            "desc": "Pauses the Sound (`Sound:Pause()`), keeping its `TimePosition`. Fires `Paused`.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 334,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Resume",
            "desc": "Resumes a paused Sound from where it stopped (`Sound:Resume()`). Fires `Resumed`.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 345,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Stop",
            "desc": "Stops the Sound (`Sound:Stop()`) and resets its `TimePosition`. Fires `Stopped`, not `Ended`,\nso the pooled sound is not returned automatically; call `Return` when you are done with it.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "source": {
                "line": 357,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Return",
            "desc": "Gives the pooled Part back to the SoundPool so it can be reused, and marks the handle as\nreturned. It does not stop the Sound first, so call `Stop` before `Return` if it is still\nplaying. Called automatically when the sound `Ended`. After this, indexing the handle (any\nproperty or method) errors, so drop your reference.",
            "params": [],
            "returns": [],
            "function_type": "method",
            "errors": [
                {
                    "lua_type": "\"Sound has already been returned.\"",
                    "desc": "Called a second time on the same playback."
                }
            ],
            "source": {
                "line": 372,
                "path": "packages/src/SoundPool/init.luau"
            }
        }
    ],
    "properties": [
        {
            "name": "Trove",
            "desc": "Holds the wrapped signals below. It is not cleaned by `Return`; clean it yourself if you keep the handle around.",
            "lua_type": "Trove",
            "source": {
                "line": 114,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "SoundInstance",
            "desc": "The pooled `Sound` that is playing. Read its properties (e.g. `TimePosition`) here; prefer `UpdateConfig` for writing.",
            "lua_type": "Sound",
            "readonly": true,
            "source": {
                "line": 120,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "PooledSound",
            "desc": "The borrowed Part the Sound is parented to; move it to move the sound in 3D.",
            "lua_type": "PooledSound",
            "readonly": true,
            "source": {
                "line": 126,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Returned",
            "desc": "`true` once the pooled sound has been given back to the pool.",
            "lua_type": "boolean",
            "readonly": true,
            "source": {
                "line": 132,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Ended",
            "desc": "Wraps `Sound.Ended`: fires with the sound id when playback finishes naturally. The pool has already returned the sound when your connection runs.",
            "lua_type": "Signal<string>",
            "readonly": true,
            "source": {
                "line": 138,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Stopped",
            "desc": "Wraps `Sound.Stopped`: fires with the sound id after `Stop`.",
            "lua_type": "Signal<string>",
            "readonly": true,
            "source": {
                "line": 144,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Paused",
            "desc": "Wraps `Sound.Paused`: fires with the sound id after `Pause`.",
            "lua_type": "Signal<string>",
            "readonly": true,
            "source": {
                "line": 150,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "Resumed",
            "desc": "Wraps `Sound.Resumed`: fires with the sound id after `Resume`.",
            "lua_type": "Signal<string>",
            "readonly": true,
            "source": {
                "line": 156,
                "path": "packages/src/SoundPool/init.luau"
            }
        },
        {
            "name": "DidLoop",
            "desc": "Wraps `Sound.DidLoop`: fires with the sound id and the loop count each time a looped sound restarts.",
            "lua_type": "Signal<string, number>",
            "readonly": true,
            "source": {
                "line": 162,
                "path": "packages/src/SoundPool/init.luau"
            }
        }
    ],
    "types": [],
    "name": "SoundPlayback",
    "desc": "A handle to one sound started by [SoundPool:PlaySound](/api/SoundPool#PlaySound). It wraps the\nborrowed `Sound` instance, lets you pause / resume / stop it or change its config while it\nplays, and returns the pooled part to the pool with `Return`. When the sound ends on its own\n(`Sound.Ended`) it is returned automatically. After `Return`, using the handle in any way\nerrors with \"Sound has already been returned.\".\n\n```lua\nlocal playback = pool:PlaySound(1234567890)\nplayback:UpdateConfig({ Volume = 0.3, Position = character.HumanoidRootPart.Position })\n\nplayback.Ended:Connect(function()\n\tprint(\"done\") -- the pooled sound has already been returned at this point\nend)\n\ntask.wait(1)\nplayback:Stop()\nplayback:Return() -- Stop does not fire Ended, so return it yourself\n```\n\nThis package is no longer maintained; see the deprecation notice on\n[SoundPool](/api/SoundPool).",
    "deprecated": {
        "version": "v1.0.0",
        "desc": "Part of the deprecated SoundPool package; no longer maintained."
    },
    "source": {
        "line": 36,
        "path": "packages/src/SoundPool/init.luau"
    }
}