Go beep Streamer返回false后为什么还要检查Err

Go beep 的Stream返回false表示流已耗尽，既可能是正常读完，也可能是读取失败。要判断任务是否成功，耗尽后还要检查该流的Err()：nil代表没有报告流读取错误，非nil则保留了失败原因。不要把ok当成error的反义词。

官方地址：https://pkg.go.dev/github.com/gopxl/beep

下文以github.com/gopxl/beep v1.4.1的接口文档为讨论范围，不把其他分支或主版本的实现混在一起。

播放结束并不意味着读取成功

考虑一个假设的排障场景：后台任务逐块读音频，看到ok变成false便写下“处理成功”。完整文件看起来正常，截断或无法继续解码的文件却也被标成成功。这不是实际事故报告，而是用来说明错误分支为何会被遗漏。

排查可以按三个观察点推进：先看是谁结束了消费，再看结束时是否保存Err，最后看是否只查了外层组合器。影响不仅是少播一段声音，还可能是离线转码、波形统计把不完整结果当成完整结果提交。

根因是把耗尽状态当成错误状态

一个Streamer有两条信息通道：Stream提供当前有效帧数n和是否产出数据的ok；Err报告流读取过程中的错误。每个元素是[2]float64，包含左右声道，因此n计的是立体声帧，不是字节数，也不是两个声道数相加。

图中的有效帧区buf[:n]与n相联系，ok描述耗尽状态，Err关联流读取错误。三者属于同一个接口契约，却回答不同问题。不能在ok为true时忽略n，也不能在ok为false时直接判定无错误。

按该版本契约，一旦Err非nil，Stream应持续返回0、false。自定义实现不应返回“n大于0同时ok为false”来模仿io.Reader的数据与错误同时返回模式；这两个接口的返回规则并不相同。

修复消费循环，结束后读取Err

下面的原创同步辅助函数只统计有限流中的有效帧，适合说明消费端怎样判断结果。它不连接扬声器，不给无限流提供停止机制，也没有执行产生任何实测输出。

package audiojob

import (
    "fmt"
    "github.com/gopxl/beep"
)

// CountFrames同步耗尽一个有限流；调用期间不能有其他消费者读取s。
// 只统计帧数，不播放、不保存音频，也不负责关闭调用方拥有的资源。
func CountFrames(s beep.Streamer) (int64, error) {
    if s == nil {
        return 0, fmt.Errorf("streamer is nil")
    }
    buf := make([][2]float64, 512)
    var total int64
    for {
        n, ok := s.Stream(buf)
        // 防止自定义实现违反契约，避免使用无效长度或空转。
        if n  len(buf) || (!ok && n != 0) || (ok && n == 0) {
            return total, fmt.Errorf("invalid Stream result: n=%d ok=%t", n, ok)
        }
        // 有效区只有buf[:n]；短块也必须计入，不能因为不足512而丢弃。
        total += int64(n)
        if !ok {
            // false只表示耗尽；Err才说明是否因读取错误而结束。
            if err := s.Err(); err != nil {
                return total, fmt.Errorf("stream failed after %d frames: %w", total, err)
            }
            return total, nil
        }
    }
}

修复点是把“循环结束”与“任务成功”拆开：先累计所有有效帧，再在耗尽分支读取Err，使用%w保留底层错误，方便调用方继续判断原因。512只是示例批大小，不是推荐的播放缓冲参数。

代码对非法n与空转返回做了防御判断，但仍依赖实现遵守完整契约，例如短块之后不再产生新数据。它不是Streamer实现的验证器。如果s已经处于错误状态，首次Stream返回0、false时同样会检查到Err。

调用方得到非nil错误时，total只代表已经消费的部分帧数，不能把这部分结果悄悄发布为完整音频。确实允许部分结果的业务，应单独标记“部分完成”和原因。

包装后应从哪里获取错误

若直接消费的是解码流，读取该流的Err比较直接。但加上组合器之后，“最外层Err”不一定代表所有子流的健康状态。该版本的Seq、Mix、Iterate不传播子流错误；Mixer的Err始终为nil，而且Mixer即使没有子流也会继续提供静音。

图中源流Err与业务错误记录直接关联；外层组合器和完成状态之间的关系，并不等价于“子流全部成功”。如果用Seq安排完成回调，应保留原始解码流引用，在具备正确同步的完成处理位置读取其Err，而不是只检查Seq的Err。

Resampler、Take与Loop在该版本中有错误传播说明，但仍需按实际使用的包装类型确认语义，不能从一个包装器推导所有包装器都传播错误。StreamerFunc的Err也始终返回nil；需要存储自定义读取错误时，应实现带错误字段的具体类型。

同步CountFrames要求独占消费权。不要把一个正在由speaker读取的同一流再交给它，否则两方争抢音频。实时播放下的状态读取、修改与关闭需要遵守speaker及具体流的同步要求；完成回调表示逻辑消费完成，也不等于设备已经把全部缓冲声音播出。

把结束、错误和资源释放分别记录

防止同类问题再次出现，业务状态至少区分“正常耗尽”“读取失败”“主动停止”。流提前被业务截断时，即使Err为nil，也不能据此证明原始输入已被完整处理；例如只消费Take限定的前一段，本来就不是完整文件任务。

Err会自动关闭文件吗？不会。Streamer本身没有Close方法；具有资源的StreamCloser或StreamSeekCloser需要由明确的所有者在不再使用时关闭。读取错误与关闭错误也应分别处理，避免后者覆盖真正的解码失败原因。

Seek失败也看Err吗？该版本StreamSeeker的Seek错误由Seek直接返回，不通过Err返回。应在调用Seek的地方处理，不能等音频结束后再补查。

可以只凭声音停止判断成功吗？不可以。正常结束、底层失败、主动停止都可能表现为没有声音，Mixer还可能继续输出静音。应把任务完成依据与听感分开。

参考：Streamer接口契约、组合器与错误传播说明。