NeteaseCloudMusicApiEnhanced/docs/RELAY_PLAY_STATE_INTEGRATION.md

relay_play_state_submit 集成说明

修改内容

1. 新增 API 接口模块

文件: module/relay_play_state_submit.js

功能: 提交歌曲播放状态，支持会话追踪和播放模式记录

接口地址: /api/relay/play/state/submit

参数说明:

• id (必填): 歌曲 ID
• sessionId (必填): 播放会话 ID（12 位大写字母和数字）
• progress (可选): 播放进度（秒），默认 0
• playMode (可选): 播放模式，默认 list_loop
• type (可选): 资源类型，默认 song

参数校验:

if (!id || !sessionId) {
  return Promise.reject({
    status: 400,
    body: {
      code: 400,
      msg: '缺少必要参数：id, sessionId',
    },
  })
}

2. 更新 API 文档

文件: public/docs/home.md

在文档末尾添加了接口说明，包括：

• 接口功能说明
• 参数列表
• 调用示例

3. 集成到自动任务脚本

文件: auto_tasks_enhanced.js

修改内容:

1. 导入接口 (Line 32):

const {
  // ... 其他接口
  relay_play_state_submit,
  // ... 其他接口
} = require('@neteasecloudmusicapienhanced/api')

2. 组合使用两个接口 (Lines 447-483):

// 2. 上传听歌记录（组合使用两个接口）
console.log('  [2] 上传播放状态...')
try {
  // 生成 sessionId（12 位大写字母和数字）
  const sessionId = Math.random().toString(36).substring(2, 8).toUpperCase() + 
                   Math.random().toString(36).substring(2, 8).toUpperCase()
  
  // 2.1 提交播放开始状态（relay_play_state_submit）
  const relayResult = await relay_play_state_submit({
    cookie,
    id: song.id,
    sessionId: sessionId,
    progress: 0,
    playMode: 'list_loop'
  })
  if (relayResult.body.code === 200) {
    console.log('    ✓ 播放状态已提交')
  }
  
  await sleep(1000)
  
  // 2.2 上传完整听歌记录（scrobble）
  const playTime = Math.floor(song.dt / 1000)
  const scrobbleResult = await scrobble({
    cookie,
    id: song.id,
    sourceid: playlistId,
    time: playTime
  })
  if (scrobbleResult.body.code === 200) {
    const timeStr = (playTime / 60).toFixed(2)
    console.log(`    ✓ 听歌记录已上传 (${timeStr}分钟)`)
    successCount++
  }
} catch (e) {
  console.log(`     上传失败：${e.message}`)
}

工作流程

完整的 VIP 音乐任务播放流程：

1. 收藏歌曲 (song_like)
   ↓
2. 提交播放状态 (relay_play_state_submit)
   ↓ (延迟 1 秒)
3. 上传听歌记录 (scrobble)
   ↓ (延迟 1 秒)
4. 等待 30-60 秒
   ↓
5. 取消收藏 (song_like)

优势

组合使用两个接口的好处：

1. relay_play_state_submit:

   • 实时播放状态同步
   • 会话追踪（sessionId）
   • 播放模式记录
   • 更符合现代播放器行为

2. scrobble:

   • 完整的听歌记录
   • 播放时长统计
   • 来源歌单记录
   • 用于任务完成判定

3. 组合效果:

   • 更真实的播放行为模拟
   • 完整的数据记录
   • 提高任务完成可靠性

Pull Request

PR #181: https://github.com/NeteaseCloudMusicApiEnhanced/api-enhanced/pull/181

提交内容:

• ✅ 新增 module/relay_play_state_submit.js
• ✅ 更新 public/docs/home.md
• ✅ 参数校验修复
• ✅ 使用示例更新

测试验证

接口已通过测试：

✓ relay_play_state_submit 成功
✓ scrobble 成功
✓ 组合使用正常

兼容性

• ✅ 保持原有 scrobble 接口不变
• ✅ 新增 relay_play_state_submit 可选使用
• ✅ 向后兼容
• ✅ 不影响现有功能