自建音乐服务 · 音质切换功能全链路实现（详细版）

┌────────────────────────────────────────────────────┐
│  Android App                                        │
│  ┌──────────────────────────────────────────────┐  │
│  │  PlayerActivity                              │  │
│  │    顶部"音质"标签  ← 点击切换                 │  │
│  │    ├ Toast 提示                               │  │
│  │    └ 更新标签文案                             │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │  PlaybackService                             │  │
│  │    currentQuality = AudioQuality.load()      │  │
│  │    setQuality(q):                            │  │
│  │      ├ 保存 SharedPreferences                 │  │
│  │      ├ 通知 listener 刷新 UI                  │  │
│  │      └ prepareCurrent(wasPlaying)            │  │
│  │         ├ 保存 pendingSeekMs                  │  │
│  │         └ 拼 URL → streamUrl(guid, quality)   │  │
│  └──────────────────────────────────────────────┘  │
│  ┌──────────────────────────────────────────────┐  │
│  │  DaoliyuApiClient                            │  │
│  │    /stream?token=xxx&q=mid                   │  │
│  └──────────────────────────────────────────────┘  │
└────────────────────────────────────────────────────┘
                       │ HTTP Range 请求
                       ▼
┌────────────────────────────────────────────────────┐
│  FastAPI 后端                                       │
│  ┌──────────────────────────────────────────────┐  │
│  │  /api/tracks/{id}/stream?q=mid               │  │
│  │    ├ 参数校验（high/mid/low）                 │  │
│  │    ├ 查库拿源文件路径                         │  │
│  │    └ transcode.ensure_transcoded()           │  │
│  │        ├ 缓存命中 → 直接返回                  │  │
│  │        ├ 未命中 → ffmpeg 转码                 │  │
│  │        │        → 原子写入缓存                 │  │
│  │        │        → 缓存清理                    │  │
│  │        └ 返回缓存文件路径                      │  │
│  │    └ range_response() 支持 HTTP Range         │  │
│  └──────────────────────────────────────────────┘  │
│                                                    │
│  DATA_DIR/transcoded/                              │
│    ├ xxxx_mid.mp3   （320k，约 7MB）              │
│    └ xxxx_low.mp3   （128k，约 3MB）              │
└────────────────────────────────────────────────────┘

TRANSCODE_DIR = DATA_DIR / "transcoded"

TRANSCODE_PROFILES = {
    "high": {"bitrate": 0,   "codec": None,  "label": "原始音质"},
    "mid":  {"bitrate": 320, "codec": "mp3", "label": "高品质 320k"},
    "low":  {"bitrate": 128, "codec": "mp3", "label": "标准 128k"},
}
DEFAULT_TRANSCODE_QUALITY = "high"

TRANSCODE_CACHE_MAX_BYTES = 5 * 1024 * 1024 * 1024   # 5 GB
FFMPEG_BIN = os.environ.get("FFMPEG_BIN", "ffmpeg")
TRANSCODE_TIMEOUT_SECONDS = 600

def ensure_dirs() -> None:
    DATA_DIR.mkdir(parents=True, exist_ok=True)
    COVER_DIR.mkdir(parents=True, exist_ok=True)
    PLAYLIST_COVER_DIR.mkdir(parents=True, exist_ok=True)
    TRANSCODE_DIR.mkdir(parents=True, exist_ok=True)

def ensure_transcoded(track_id: str, source_path: Path, quality: str) -> Path:
    """确保某档位缓存已存在，返回可供流式响应的文件路径。"""

def get_transcoded_path(track_id, source_path, quality):
    if quality not in TRANSCODE_PROFILES:
        quality = "high"
    prof = TRANSCODE_PROFILES[quality]
    if prof["codec"] is None:
        return source_path   # high 直接用源文件

    try:
        mtime = int(source_path.stat().st_mtime)
    except OSError:
        mtime = 0
    safe_key = f"{track_id}|{quality}|{mtime}"
    digest = hashlib.sha1(safe_key.encode("utf-8")).hexdigest()[:16]
    return TRANSCODE_DIR / f"{digest}_{quality}.mp3"

cmd = [
    FFMPEG_BIN, "-hide_banner", "-loglevel", "error", "-y",
    "-i", str(source_path),
    "-vn",                      # 忽略视频流（封面）
    "-map_metadata", "-1",      # 不带元数据（减小体积）
    "-c:a", "libmp3lame",       # mp3 编码器
    "-b:a", f"{bitrate}k",      # 码率
    "-f", "mp3",                # 强制 mp3 格式
    str(tmp),                   # 先写临时文件
]

tmp = target.with_suffix(".mp3.part")
# ... subprocess.run(cmd) ...
os.replace(tmp, target)

try:
    result = subprocess.run(cmd, timeout=TRANSCODE_TIMEOUT_SECONDS, ...)
except subprocess.TimeoutExpired:
    _safe_unlink(tmp)
    raise TranscodeError(f"转码超时（>{TRANSCODE_TIMEOUT_SECONDS}s）")
except FileNotFoundError:
    _safe_unlink(tmp)
    raise TranscodeError(f"找不到 ffmpeg：{FFMPEG_BIN}")

if result.returncode != 0:
    _safe_unlink(tmp)
    err = (result.stderr or b"").decode("utf-8", "replace").strip()
    raise TranscodeError(f"ffmpeg 退出码 {result.returncode}：{err[:300]}")

def _cleanup_cache_if_needed() -> None:
    """缓存超过上限时，按 mtime 从旧到新删除。"""
    files = []
    total = 0
    for entry in TRANSCODE_DIR.iterdir():
        if not entry.is_file():
            continue
        st = entry.stat()
        files.append((st.st_mtime, st.st_size, entry))
        total += st.st_size

    if total <= TRANSCODE_CACHE_MAX_BYTES:
        return

    files.sort(key=lambda x: x[0])   # 旧 -> 新
    removed_bytes = 0
    for _, size, path in files:
        if total - removed_bytes <= TRANSCODE_CACHE_MAX_BYTES:
            break
        _safe_unlink(path)
        removed_bytes += size

@app.get("/api/tracks/{track_id}/stream")
def stream_track(
    track_id: str,
    request: Request,
    token: str = "",
    q: str = "",
    authorization: str = Header(None),
):
    # 1. 认证
    user = _resolve_stream_user(token, authorization or "")
    if user is None:
        raise HTTPException(401, "登录已失效，请重新登录")

    # 2. 参数校验
    quality = (q or "").strip().lower() or "high"
    if not is_quality_supported(quality):
        raise HTTPException(400, f"不支持的音质档位：{quality}")

    # 3. 查库
    with get_db() as conn:
        row = conn.execute(
            "SELECT path FROM tracks WHERE id = ?", (track_id,)
        ).fetchone()
    if row is None:
        raise HTTPException(404, "歌曲不存在")

    audio_path = safe_join(MUSIC_ROOT, row["path"])
    if audio_path is None or not audio_path.is_file():
        raise HTTPException(404, "音频文件不存在")

    # 4. 确保转码
    try:
        play_path = ensure_transcoded(track_id, audio_path, quality)
    except TranscodeError as e:
        logger.warning("转码失败 %s [%s]: %s", track_id, quality, e)
        play_path = audio_path   # ★ 优雅降级：退回原文件
        # 注意：不 raise，让用户至少能听原版

    # 5. 流式响应（支持 Range）
    range_header = (request.headers.get("range")
                    or request.headers.get("Range"))
    return range_response(play_path, range_header)

@app.get("/api/qualities")
def api_qualities(user: dict = Depends(require_auth)):
    """给客户端列出可用音质档位。"""
    return {"items": list_qualities()}

{"items": [
  {"key": "high", "label": "原始音质", "bitrate": 0},
  {"key": "mid",  "label": "高品质 320k", "bitrate": 320},
  {"key": "low",  "label": "标准 128k", "bitrate": 128}
]}

public enum AudioQuality {
    HIGH("high", "原", "原始音质"),
    MID("mid",   "320", "高品质 320k"),
    LOW("low",   "128", "标准 128k");

    public final String key;        // 传给后端的 q 参数
    public final String shortLabel; // 按钮上显示的短标签
    public final String label;      // Toast / 面板上显示的全称

    AudioQuality(String key, String shortLabel, String label) {
        this.key = key;
        this.shortLabel = shortLabel;
        this.label = label;
    }

    // SharedPreferences 持久化
    private static final String PREFS = "audio_settings";
    private static final String KEY_QUALITY = "audio_quality";

    public static AudioQuality load(Context ctx) {
        if (ctx == null) return HIGH;
        SharedPreferences sp = ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE);
        String saved = sp.getString(KEY_QUALITY, HIGH.key);
        return fromKey(saved);
    }

    public static void save(Context ctx, AudioQuality q) {
        if (ctx == null || q == null) return;
        ctx.getSharedPreferences(PREFS, Context.MODE_PRIVATE)
           .edit().putString(KEY_QUALITY, q.key).apply();
    }

    public static AudioQuality fromKey(String key) {
        if (key != null) {
            for (AudioQuality q : values()) {
                if (q.key.equals(key)) return q;
            }
        }
        return HIGH;
    }

    /** 循环切换：原 → 320 → 128 → 原 */
    public AudioQuality next() {
        switch (this) {
            case HIGH: return MID;
            case MID:  return LOW;
            case LOW:  return HIGH;
            default:   return HIGH;
        }
    }
}

/** 默认音质：HIGH（原始）。保持向后兼容。 */
@Override
public String streamUrl(String guid) {
    return streamUrl(guid, AudioQuality.HIGH);
}

/**
 * 带音质档位的流地址。
 *
 * 后端三档：
 *   high → 原始文件
 *   mid  → 320k mp3（服务端转码缓存）
 *   low  → 128k mp3
 */
public String streamUrl(String guid, AudioQuality quality) {
    String base = session.getBaseUrl();
    AudioQuality q = (quality == null) ? AudioQuality.HIGH : quality;
    return base + API_PREFIX + "/tracks/" + Uri.encode(guid) + "/stream"
            + "?token=" + Uri.encode(session.getToken())
            + "&q=" + q.key;
}

private AudioQuality currentQuality = AudioQuality.HIGH;

/** 音质切换监听器，供 UI 层注册。 */
private final List<OnQualityChangedListener> qualityListeners =
        new CopyOnWriteArrayList<OnQualityChangedListener>();

public interface OnQualityChangedListener {
    void onQualityChanged(AudioQuality q);
}

@Override
public void onCreate() {
    super.onCreate();
    // ... 原有初始化
    currentQuality = AudioQuality.load(this);   // ★ 新增
    // ... 后续初始化
}

public AudioQuality getQuality() {
    return currentQuality;
}

/**
 * 切换音质：
 * - 若正在播放：保持当前进度和播放状态，重新加载当前曲
 * - 若暂停中：仅更新状态，下次播放时用新档位
 */
public void setQuality(AudioQuality q) {
    if (q == null || q == currentQuality) return;
    currentQuality = q;
    AudioQuality.save(this, q);
    notifyQualityChanged(q);

    Track cur = currentIndex >= 0 && currentIndex < queue.size()
            ? queue.get(currentIndex) : null;
    if (cur == null) return;

    int pos = getPositionMs();
    boolean wasPlaying = isPlaying();

    // ★ 关键：让 prepareInternal 里的 pendingSeekMs 生效，保持进度
    pendingSeekMs = Math.max(0, pos);
    playWhenPrepared = wasPlaying;
    prepareCurrent(wasPlaying);
}

public void addQualityListener(OnQualityChangedListener l) {
    if (l != null && !qualityListeners.contains(l)) qualityListeners.add(l);
}

public void removeQualityListener(OnQualityChangedListener l) {
    qualityListeners.remove(l);
}

private void notifyQualityChanged(AudioQuality q) {
    for (OnQualityChangedListener l : qualityListeners) {
        try { l.onQualityChanged(q); } catch (Exception ignored) { }
    }
}

// 原来
File localFile = allowLocalCache ? trackCache.getCompleteFile(track.guid) : null;

// 现在
File localFile = (allowLocalCache && currentQuality == AudioQuality.HIGH)
        ? trackCache.getCompleteFile(track.guid) : null;

// 原来
String url = source.streamUrl(track.guid);

// 现在
String url;
if (source instanceof DaoliyuApiClient) {
    url = ((DaoliyuApiClient) source).streamUrl(track.guid, currentQuality);
} else {
    // 其他音源（飞牛等）暂未实现音质降级
    url = source.streamUrl(track.guid);
}

private void prefetchTrack(final Track track) {
    // ★ 只在原始音质下做缓存，避免高低音质共用缓存文件
    if (currentQuality != AudioQuality.HIGH) return;
    // ... 原有逻辑
}

/** 音质切换监听器（UI 主动刷新用）。 */
private final PlaybackService.OnQualityChangedListener qualityListener =
        new PlaybackService.OnQualityChangedListener() {
            @Override public void onQualityChanged(AudioQuality q) {
                runOnUiThread(new Runnable() {
                    @Override public void run() { updateQualityLabel(); }
                });
            }
        };

quality = (TextView) findViewById(R.id.player_quality);

// ★ 顶部"音质"标签：点击循环切换档位
quality.setOnClickListener(new View.OnClickListener() {
    @Override public void onClick(View v) { onQualityClick(); }
});

/** 点击顶部音质标签：循环切到下一档。 */
private void onQualityClick() {
    if (playback == null) {
        Toast.makeText(this, "播放服务未就绪", Toast.LENGTH_SHORT).show();
        return;
    }
    AudioQuality next = playback.getQuality().next();
    playback.setQuality(next);
    updateQualityLabel();
    Toast.makeText(this, "音质 · " + next.label, Toast.LENGTH_SHORT).show();
}

/** 刷新顶部音质标签：档位 + 源文件参数（如 FLAC 24bit 96kHz）。 */
private void updateQualityLabel() {
    if (quality == null || playback == null) return;
    AudioQuality q = playback.getQuality();
    Track track = playback.snapshot().track;
    String codec = (track != null) ? track.qualityLabel() : "";
    if (codec == null || codec.length() == 0) {
        quality.setText("音质 · " + q.shortLabel);
    } else {
        quality.setText("音质 · " + q.shortLabel + " · " + codec);
    }
}

// 原来
quality.setText(track.qualityLabel());

// 现在
updateQualityLabel();

@Override
public void onServiceConnected(ComponentName name, IBinder service) {
    playback = ((PlaybackService.LocalBinder) service).getService();
    bound = true;
    playback.addQualityListener(qualityListener);   // ★ 注册
    updateUi();
    updateQualityLabel();                          // ★ 首次同步
}

@Override protected void onStop() {
    if (bound && playback != null) {
        playback.removeQualityListener(qualityListener);   // ★ 注销
    }
    handler.removeCallbacks(update);
    if (bound) {
        unbindService(connection);
        bound = false;
        playback = null;
    }
    super.onStop();
}

<!-- 原来：纯展示 -->
<TextView
    android:id="@+id/player_quality"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="3dp"
    android:includeFontPadding="false"
    android:text="音质"
    android:textColor="@color/primary"
    android:textSize="11sp"
    android:textStyle="bold" />

<!-- 现在：可点击胶囊按钮 -->
<TextView
    android:id="@+id/player_quality"
    android:layout_width="wrap_content"
    android:layout_height="wrap_content"
    android:layout_marginTop="3dp"
    android:background="@drawable/bg_quality_chip"
    android:clickable="true"
    android:focusable="true"
    android:includeFontPadding="false"
    android:paddingLeft="10dp"
    android:paddingTop="3dp"
    android:paddingRight="10dp"
    android:paddingBottom="3dp"
    android:text="音质 · 原"
    android:textColor="@color/primary"
    android:textSize="11sp"
    android:textStyle="bold" />

<?xml version="1.0" encoding="utf-8"?>
<shape xmlns:android="http://schemas.android.com/apk/res/android"
    android:shape="rectangle">
    <solid android:color="#1AFFFFFF" />
    <corners android:radius="12dp" />
    <stroke android:width="1dp" android:color="#33FFFFFF" />
</shape>

cd /tmp
wget https://johnvansickle.com/ffmpeg/releases/ffmpeg-release-amd64-static.tar.xz
tar xvf ffmpeg-release-amd64-static.tar.xz
sudo cp ffmpeg-*-static/ffmpeg /usr/local/bin/
sudo cp ffmpeg-*-static/ffprobe /usr/local/bin/
sudo chmod +x /usr/local/bin/ffmpeg /usr/local/bin/ffprobe

# 验证（任何目录都能跑）
ffmpeg -version | head -1

systemctl restart mydaoliyu-music
tail -f /var/log/mydaoliyu-music.log

TRANSCODE_DIR      = /usr/local/music_player/data/transcoded
FFMPEG_BIN         = ffmpeg

error: resource drawable/bg_quality_chip not found

# 看转码缓存目录
ls -lh /usr/local/music_player/data/transcoded/

# 看实时日志
tail -f /var/log/mydaoliyu-music.log | grep -i transcode

-rw-r--r-- 1 root root 7.2M  xxxx_mid.mp3
-rw-r--r-- 1 root root 2.9M  xxxx_low.mp3

2026-09-25 15:08:18 [INFO] transcode: 转码完成 [low] 周杰伦 - 定格.flac -> 2.9 MB，用时 5.0s
2026-09-25 15:08:34 [INFO] transcode: 转码完成 [low] 顺德老莫 - 得意的笑.flac -> 3.8 MB，用时 6.8s

adb logcat -s PlaybackService:* | grep -E "prepareInternal|Prepared"

prepareInternal: url http://xxx:42121/api/tracks/trk_xxx/stream?token=xxx&q=mid
Prepared stream in 1234 ms, source=url http://xxx...&q=mid

#!/bin/bash
TOKEN="你的token"
TRACK="trk_xxx"
BASE="http://127.0.0.1:42121"

echo "=== 三档响应 ==="
for Q in high mid low; do
  echo "--- q=$Q ---"
  curl -sI "$BASE/api/tracks/$TRACK/stream?token=$TOKEN&q=$Q" \
    | grep -iE 'HTTP/|content-type|content-length'
  echo
done

echo "=== 转码缓存 ==="
ls -lh /usr/local/music_player/data/transcoded/ | tail -10

echo "=== 最近转码日志 ==="
tail -20 /var/log/mydaoliyu-music.log | grep -i transcode

Get-ChildItem -Recurse -Filter "bg_quality_chip.xml" E:\SourceCode\FeiniuYuMusic

pendingSeekMs = Math.max(0, getPositionMs());
playWhenPrepared = isPlaying();
prepareCurrent(playWhenPrepared);

File localFile = (allowLocalCache && currentQuality == AudioQuality.HIGH)
        ? trackCache.getCompleteFile(track.guid) : null;

# 错误写法：ffmpeg 报错时不抛异常，后续处理会拿到半损坏的文件
result = subprocess.run(cmd, ...)

# 正确写法：显式检查 returncode
if result.returncode != 0:
    raise TranscodeError(...)

safe_key = f"{track_id}|{quality}|{source_mtime}"
digest = hashlib.sha1(safe_key.encode()).hexdigest()[:16]

ConnectivityManager cm = (ConnectivityManager)
        getSystemService(Context.CONNECTIVITY_SERVICE);
NetworkCapabilities caps = cm.getNetworkCapabilities(cm.getActiveNetwork());

if (caps.hasTransport(NetworkCapabilities.TRANSPORT_CELLULAR)) {
    // 4G → 自动切 low
    playback.setQuality(AudioQuality.LOW);
} else if (caps.hasTransport(NetworkCapabilities.TRANSPORT_WIFI)) {
    // WiFi → 自动切 high
    playback.setQuality(AudioQuality.HIGH);
}

AudioQuality q = AudioQuality.load(this);
String url = client.streamUrl(track.guid, q);

new AlertDialog.Builder(this)
    .setTitle("选择音质")
    .setSingleChoiceItems(labels, currentIdx, (dialog, which) -> {
        playback.setQuality(all[which]);
        dialog.dismiss();
    })
    .show();

# scanner.py 尾部
for row in conn.execute("SELECT id, path FROM tracks").fetchall():
    src = MUSIC_ROOT / row["path"]
    if src.is_file():
        try:
            ensure_transcoded(row["id"], src, "mid")
        except Exception:
            pass

@app.get("/api/tracks/{id}/transcode-progress")
async def transcode_progress(track_id: str, quality: str):
    # 通过读取 ffmpeg 的 stderr 解析进度
    ...