最后同步日期：2026-04-15 | Godot 官方原文 — AudioStreamPlayer.get_playback_position

AudioStreamPlayer.get_playback_position

定义

AudioStreamPlayer.get_playback_position 就是查询当前音频播放到了哪个位置——也就是音频已经播了多少秒。就像你看视频时底部进度条上的时间显示。

打个比方：一首歌总长 3 分钟，你听到一半，get_playback_position 就会返回大约 90 秒。你可以用这个信息来显示进度条、计算剩余时间等。

在实际游戏开发中，你经常需要知道当前播放位置来实现音频进度条、歌词同步、或者检测音频是否快要播完了。

函数签名

C#

public float GetPlaybackPosition()

GDScript

func get_playback_position() -> float

参数说明

参数	类型	必需	说明
无	—	—	此方法没有参数

返回值

float —— 当前播放位置，单位是秒。返回值范围从 0.0（开头）到音频总时长（结尾）。如果音频没有在播放，返回上次停止时的位置。

代码示例

基础用法：获取当前播放位置

C#

var player = GetNode<AudioStreamPlayer>("MusicPlayer");

player.Play();
// ... 过了一会儿 ...
float pos = player.GetPlaybackPosition();
GD.Print($"当前播放位置：{pos} 秒");
// 运行结果: 打印类似 "当前播放位置：12.5 秒"

GDScript

var player = $MusicPlayer as AudioStreamPlayer

player.play()
# ... 过了一会儿 ...
var pos = player.get_playback_position()
print("当前播放位置：%s 秒" % pos)
# 运行结果: 打印类似 "当前播放位置：12.5 秒"

实际场景：显示音频播放进度条

C#

using Godot;

public partial class AudioProgressBar : Control
{
    private AudioStreamPlayer _musicPlayer;
    private ProgressBar _progressBar;
    private Label _timeLabel;
    private float _totalDuration = 0.0f;

    public override void _Ready()
    {
        _musicPlayer = GetNode<AudioStreamPlayer>("MusicPlayer");
        _progressBar = GetNode<ProgressBar>("ProgressBar");
        _timeLabel = GetNode<Label>("TimeLabel");
    }

    public void SetMusic(AudioStream stream)
    {
        _musicPlayer.Stream = stream;
        _totalDuration = (float)stream.GetLength();
        _musicPlayer.Play();
    }

    public override void _Process(double delta)
    {
        if (_musicPlayer.Playing && _totalDuration > 0)
        {
            float currentPos = _musicPlayer.GetPlaybackPosition();
            float ratio = currentPos / _totalDuration;

            _progressBar.Value = ratio * 100.0f;

            int elapsed = (int)currentPos;
            int remaining = (int)(_totalDuration - currentPos);
            _timeLabel.Text = $"{FormatTime(elapsed)} / {FormatTime((int)_totalDuration)}";
            // 运行结果: 进度条实时更新，标签显示如 "01:23 / 03:45"
        }
    }

    private string FormatTime(int seconds)
    {
        return $"{seconds / 60:D2}:{seconds % 60:D2}";
    }
}

GDScript

extends Control

@onready var _music_player: AudioStreamPlayer = $MusicPlayer
@onready var _progress_bar: ProgressBar = $ProgressBar
@onready var _time_label: Label = $TimeLabel
var _total_duration: float = 0.0

func set_music(stream: AudioStream):
    _music_player.stream = stream
    _total_duration = stream.get_length()
    _music_player.play()

func _process(delta):
    if _music_player.playing and _total_duration > 0:
        var current_pos = _music_player.get_playback_position()
        var ratio = current_pos / _total_duration

        _progress_bar.value = ratio * 100.0

        var elapsed = int(current_pos)
        var remaining = int(_total_duration - current_pos)
        _time_label.text = "%s / %s" % [format_time(elapsed), format_time(int(_total_duration))]
        # 运行结果: 进度条实时更新，标签显示如 "01:23 / 03:45"

func format_time(seconds: int) -> String:
    return "%02d:%02d" % [seconds / 60, seconds % 60]

进阶用法：记录播放位置并在恢复时续播

C#

using Godot;

public partial class ResumableAudio : Node
{
    private AudioStreamPlayer _player;
    private float _savedPosition = 0.0f;

    public override void _Ready()
    {
        _player = GetNode<AudioStreamPlayer>("MusicPlayer");
    }

    public void PauseAndSave()
    {
        // 保存当前播放位置然后停止
        _savedPosition = _player.GetPlaybackPosition();
        _player.Stop();
        GD.Print($"音频暂停在 {_savedPosition:F2} 秒");
        // 运行结果: 打印暂停位置，如 "音频暂停在 45.67 秒"
    }

    public void ResumeFromSaved()
    {
        // 从上次暂停的位置继续播放
        _player.Play(_savedPosition);
        GD.Print($"从 {_savedPosition:F2} 秒恢复播放");
        // 运行结果: 从保存的位置继续播放
    }
}

GDScript

extends Node

@onready var _player: AudioStreamPlayer = $MusicPlayer
var _saved_position: float = 0.0

func pause_and_save():
    # 保存当前播放位置然后停止
    _saved_position = _player.get_playback_position()
    _player.stop()
    print("音频暂停在 %.2f 秒" % _saved_position)
    # 运行结果: 打印暂停位置，如 "音频暂停在 45.67 秒"

func resume_from_saved():
    # 从上次暂停的位置继续播放
    _player.play(_saved_position)
    print("从 %.2f 秒恢复播放" % _saved_position)
    # 运行结果: 从保存的位置继续播放

注意事项

• 精度可能有微小偏差：返回的位置可能有几毫秒的误差，这是因为音频引擎使用缓冲区机制。对于大多数用途（进度条、时间显示）来说，这个误差可以忽略不计。
• 在未播放时返回上次停止位置：如果音频已经停止，GetPlaybackPosition() 返回的是停止时的位置（或上次调用 Play(fromPosition) 时指定的位置）。
• 与 Stream.GetLength() 配合：要获取音频总时长，使用 Stream.GetLength() 方法。两者配合可以计算播放进度百分比。
• AudioStream 和 AudioStreamPlayer 的区别：GetPlaybackPosition() 是 Player 的方法，返回的是播放器中的当前时间；GetLength() 是 Stream 的方法，返回的是音频文件的总时长。