Tiddl项目：解决播放列表下载限制与文件名格式问题

Tiddl项目：解决播放列表下载限制与文件名格式问题

tiddl Download Tidal tracks, videos, albums, playlists & artists! Python downloader that supports master quality. 项目地址: https://gitcode.com/gh_mirrors/ti/tiddl

项目背景

Tiddl是一个基于Python开发的Tidal音乐平台下载工具，作为已停用Tidal下载器的后继项目，它提供了从Tidal平台下载音乐的功能。该项目支持多种音质选择和自定义文件名格式，但在实际使用中用户发现了一些功能限制。

问题分析

在Tiddl 1.8.0版本中，用户报告了两个主要问题：

1. 播放列表下载限制：工具只能下载播放列表中的前50首歌曲，无法完整获取大型播放列表内容。

2. 文件名格式失效：使用-o参数指定的文件名模板在播放列表下载场景下不生效，系统默认使用简单的曲目标题作为文件名。

技术解决方案

播放列表下载限制的解决

原实现仅获取播放列表的第一页数据（默认50条）。为解决这个问题，开发者实现了分页获取机制：

1. 初始化参数：设置偏移量(offset)为0，每页限制(limit)为50
2. 循环获取数据：通过API分页请求，直到获取不到新数据为止
3. 合并结果：将每页获取的曲目合并到完整列表中

核心代码逻辑如下：

playlist_items = []
offset = 0
limit = 50

while True:
    response = api.getPlaylistItems(input_id, limit=limit, offset=offset)
    items = response["items"]
    
    if not items:
        break
        
    playlist_items.extend(items)
    offset += limit

文件名格式问题的优化

原系统对不同下载场景使用不同的文件名模板：

• 单曲下载：使用track_template
• 专辑下载：使用album_template
• 播放列表下载：强制使用playlist_template

改进方案包括：

1. 扩展格式化函数，支持播放列表序号参数
2. 统一模板处理逻辑，允许用户自定义播放列表下载时的文件名格式
3. 新增playlist_number变量，支持在模板中使用{playlist_number}占位符

格式化函数增强后支持以下变量：

• {artist} - 艺术家名称
• {title} - 曲目标题
• {playlist} - 播放列表名称
• {playlist_number} - 曲目在播放列表中的序号

使用建议

用户现在可以通过以下方式优化下载体验：

1. 完整下载大型播放列表：系统会自动分页获取所有曲目
2. 自定义文件名格式：例如使用tiddl 'playlist' -o "{playlist_number}. {artist} - {title}"格式
3. 处理无效曲目：当遇到下架曲目时，系统会记录到"missing_tracks.txt"文件

技术实现细节

1. 分页机制：利用Tidal API的offset和limit参数实现数据分片获取
2. 错误处理：对API返回的无效流数据进行检测和记录
3. 模板引擎：增强的格式化函数支持更多上下文变量
4. 并发控制：保留原有的随机延时机制，避免请求频率过高

总结

通过对Tiddl项目的这两项改进，用户现在可以更灵活地下载和管理Tidal平台上的音乐内容。特别是对于大型播放列表的支持和增强的文件名模板功能，大大提升了工具在实际使用中的便利性。这些改进体现了开源项目持续迭代优化的特点，也展示了开发者对用户反馈的积极响应。

tiddl Download Tidal tracks, videos, albums, playlists & artists! Python downloader that supports master quality. 项目地址: https://gitcode.com/gh_mirrors/ti/tiddl