Kindle Music

列出曲库全部可用的筛选值（流派/情绪/乐器/速度/适用场景/厂牌）。 Lists every filterable facet value in the catalog (genre, mood, instrumentation, tempo, music-for, label). 何时用 / When: 在 km_search 里使用任何 include*/exclude* 筛选之前，先用本工具确认取值。 Call this BEFORE using any include*/exclude* filter in km_search. 入参 / Args: field（可选，facet 字段名子串，如 "genre"/"mood"/"library"）；query（可选，对取值与中文名做不区分大小写的子串过滤，中文也能查，如 query="悲伤"）。 返回 / Returns: 每个 facet 字段的 { param, values }，values 里每项是 { value, labelZh, count }。param 就是 km_search 里该字段对应的入参名。 顶层另有 labels[]：320 个厂牌的 { library_name, library_type, company, album_count, track_count }，可用来判断某个厂牌值不值得单独收窄。 ⚠️ value 必须**原样**回填到 km_search，不要翻译、改大小写或去掉 "Parent;Leaf" 里的分号；改动过的值一律匹配不上。labelZh 只供你把中文 brief 映射到 canonical 值，不要回填。 count 用来防过度收窄：候选值 count < 200 时考虑放宽或换父级（例：`sad` 有 8.6 万首，而叶子 `sad;breakup` 只有 38 首，直接用叶子会把结果掐死）。

{
  "type": "object",
  "properties": {
    "field": {
      "type": "string",
      "description": "Substring of a facet field name, e.g. \"genre\", \"mood\", \"instrumentation\", \"library\"."
    },
    "query": {
      "type": "string",
      "description": "Case-insensitive substring filter applied to the facet values and their Chinese labels."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

在 Kindle Music 正版曲库里检索曲目或专辑，支持关键词、facet 筛选、BPM 与时长区间。 Searches the Kindle Music production-music catalog: keyword + facet filters + bpm/duration ranges. searchField 怎么选 / Choosing searchField: - keywords：关键词匹配，默认值。多个词之间是 OR、按命中词数排序，所以加不同维度的词（用途 + 情绪 + 乐器）比堆近义词有用；英文加双引号是短语匹配（"epic trailer"）。不要写 AND/OR/NOT；开头的 -term 按字面匹配，不表示排除。 剧情词和抽象词（逆袭、对峙、回忆、高级感）曲库标签里很少出现，会把排序带偏：先翻译成情绪 / 乐器 / 速度这类音乐描述再检索。 expand="fast"：中文按词翻译 + 同义扩展（结果稳定，同一个词每次扩成一样）；expand="deep"：映射到曲库标准词，召回更窄、最慢约 1 分钟。不带 expand 时 keyword 必须是英文。 带 expand 时中文否定从句（不要X / 去掉X / 避免X）会从 keyword 里剥离并映射成 exclude（「不要太X」这类程度否定映射成降权），一次最多 3 条，结果见 derivedNegations。 - ai：一句自然语言描述（可中文），后端整句理解改写后检索，结果看前排而不是总数。一两个词的需求用 keywords 更好。 - semantic：text→audio 语义检索（英文效果最好），适合"听感"类描述；不可用或 0 结果时自动降级 ai。 - track：按英文原曲名查（去掉前导序号与扩展名，中文译名搜不到）。album：按专辑编号/名查，编号不区分大小写、连字符、空格与前导零。 - lyrics：按歌词查（可中文）。composer：按作曲者查（只能英文）。 - 手里是下载文件名、UPM 链接、本站链接或 PUC-045 这类编号时，先用 km_resolve 定位，不要拿它当关键词。 ⚠️ 硬约束 / Hard constraint: searchField=keywords（未带 expand）或 composer 时 keyword 只能是英文。 Passing Chinese with searchField=composer, or with keywords and no expand, is rejected up front (Solr matches literally → zero hits). 否定 / Negation: - keywords：英文的 no / without X 不会被识别（反而把 X 当正向词召回），用 exclude*；中文否定需带 expand（见上）。客户的硬性排除任何模式都用 exclude* 兜底。 - ai：直接写进句子（不要/无/别/去掉/避免 X，no/not/without X），一次最多 4 项；「不要太X」只让 X 往后排不去掉；排除后 0 结果会自动放宽。 响应里的 derivedNegations 说明每条否定被映射成了哪个 facet 值、是否被放宽——交付前核对它。 include*/exclude* 的取值必须先用 km_vocabulary 取，并原样回填。同一维度多个值是 AND（includeLabels / includeAlbums 例外，是 OR）；exclude* 命中任一即排除。 关键词不匹配厂牌名，按厂牌收窄用 includeLabels。 partition：independent = 网站「独立精选」分区，universal = 「环球UPM」分区；不传 = 两个分区合并检索（网站精选站默认只显示独立精选）。 bpmMin/bpmMax 与 durationMin/durationMax（秒）必须成对给出。 fields 怎么选 / Choosing fields: - slim（默认）：每首 25 个字段（含 track_number、四维标签 + 中英文描述 + 可播放的 url），够直接做精排与交付。pageSize 上限 50。 - compact：每首只回 10 个字段（id / album_code / track_number / track_title / track_version / track_bpm / track_duration / library_name / library_type / web_url），pageSize 上限放宽到 200。 没有"按 id 批量取全字段"的端点：compact 结果需要中文描述与四维标签时，只能对收窄后的条件重跑一次 fields=slim。 ⚠️ BPM 半速口径 / Half-time BPM: 本曲库 55/60 与 110/120 常常是同一个脉冲的两种记法（标注方按半速还是双速记没有统一）。 在架主曲落在 60–90 BPM 的有 12.6 万首，一刀切 bpmMin=95,bpmMax=125 会静默漏掉一大片听感完全对的曲子。 按 BPM 收窄时要把半速区间也检索一遍再合并，否则会漏召回。 返回 / Returns: { total, appliedSearchField, searchId, fields, tracks[]（字段集见 fields，含可直接打开的 web_url）, search_url（C 端复现本次检索的链接）}。 有扩展时另带 ai_keyword / expanded（实际检索用的英文词）；有否定时带 derivedNegations。 translation_failed:true 表示中文扩展失败、按空结果返回，不代表曲库里没有：换英文或改 searchField=ai 重试。 ai / lyrics / expand 受后端每日 LLM 配额；超额时返回 llmQuotaExceeded:true 且 appliedSearchField 降级为 keywords。 返回的 track_url 仅供试听/临时分析，见 audioNotice。 Returned track_url values are for audition / temporary analysis only; see audioNotice.

{
  "type": "object",
  "properties": {
    "keyword": {
      "type": "string",
      "description": "Query text. MUST be English for composer, and for keywords unless expand is set."
    },
    "searchField": {
      "type": "string",
      "enum": [
        "keywords",
        "ai",
        "semantic",
        "album",
        "track",
        "lyrics",
        "composer"
      ],
      "description": "Default \"keywords\". Use \"ai\" for natural-language / Chinese briefs."
    },
    "expand": {
      "type": "string",
      "enum": [
        "fast",
        "deep"
      ],
      "description": "keywords mode only. \"fast\": translate + expand Chinese per word. \"deep\": map to canonical catalog terms (narrower, up to ~1 min)."
    },
    "view": {
      "type": "string",
      "enum": [
        "tracks",
        "albums"
      ],
      "description": "Default \"tracks\"."
    },
    "sort": {
      "type": "string",
      "enum": [
        "relevance",
        "newest",
        "oldest",
        "duration"
      ]
    },
    "page": {
      "type": "integer",
      "minimum": 1,
      "description": "1-based page number, default 1."
    },
    "pageSize": {
      "type": "integer",
      "minimum": 1,
      "description": "Default 20. Clamped to 50 with fields=\"slim\", to 200 with fields=\"compact\"."
    },
    "fields": {
      "type": "string",
      "enum": [
        "slim",
        "compact"
      ],
      "description": "Track field set. Default \"slim\" (25 fields). \"compact\" returns 10 fields and allows pageSize up to 200."
    },
    "bpmMin": {
      "type": "integer",
      "description": "Give together with bpmMax."
    },
    "bpmMax": {
      "type": "integer"
    },
    "durationMin": {
      "type": "integer",
      "description": "Seconds. Give together with durationMax."
    },
    "durationMax": {
      "type": "integer"
    },
    "libraryType": {
      "type": "string",
      "description": "e.g. \"production\" | \"trailer\" | \"promotion\"."
    },
    "partition": {
      "type": "string",
      "enum": [
        "independent",
        "universal"
      ],
      "description": "Site partition: \"independent\" (独立精选) or \"universal\" (环球UPM). Omit to search both."
    },
    "withFacets": {
      "type": "boolean",
      "description": "Also return facet counts for the current result set (slower). Default false."
    },
    "includeLabels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeLabels: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeLabels": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeLabels: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeAlbums": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeAlbums: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeAlbums": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeAlbums: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeInstrumentation": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeInstrumentation: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeInstrumentation": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeInstrumentation: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeTempo": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeTempo: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeTempo": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeTempo: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeGenre": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeGenre: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeGenre": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeGenre: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeMood": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeMood: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeMood": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeMood: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "includeMusicFor": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "includeMusicFor: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    },
    "excludeMusicFor": {
      "type": "array",
      "items": {
        "type": "string"
      },
      "description": "excludeMusicFor: facet values copied verbatim from km_vocabulary (\"Parent\" or \"Parent;Leaf\")."
    }
  },
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

列出同一首曲子的全部剪辑版本（Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec 等）。 Lists every cutdown version of one track (Full Length / 60 Sec / 30 Sec / 20 Sec / 15 Sec …). ⚠️ km_search 只索引主曲（Solr 里 track_is_main=Y），**剪辑版拿不到**，只能靠本工具取。 km_search only indexes main tracks; the shorter cutdowns are invisible to it and can ONLY be fetched here. 何时用 / When: 广告、TVC、预告片这类有硬性时长的项目，交付候选之前对每首都查一次—— 有现成的 60s/30s/15s 版本，客户就不必自己剪；没有就要在交付说明里讲清楚需要自行剪辑。 入参 / Args: albumCode = 曲目的 album_code；trackNumber = **主曲**的 track_number（都取自 km_search 返回的曲目对象）。 libraryType 可选：原样透传 km_search 里那首曲子的 library_type，用来判定 web_url 的 essential / premium 段（本端点自身不返回该字段）。 返回 / Returns: { albumCode, trackNumber, total, versions[] }，versions 按时长从长到短排，字段与 km_search 的曲目对象同构。 看 track_version（版本名）、track_duration（秒）、orginal_time（mm:ss）、track_mixout（如 Backing Vocals Only，即去人声版）。 注意：剪辑版只有版本名 / 时长 / mixout / 英文描述，track_bpm 与四维标签（mood/genre/instrumentation/tempo）只有主曲那行有——它们本来就是同一首曲子，按主曲的值理解即可。 专辑号或曲目号不存在时返回空 versions[]，不报错。 返回的 track_url 仅供试听/临时分析，见 audioNotice。 Returned track_url values are for audition / temporary analysis only; see audioNotice.

{
  "type": "object",
  "properties": {
    "albumCode": {
      "type": "string",
      "description": "Album code as returned by km_search (field \"album_code\"), e.g. \"NYB17\"."
    },
    "trackNumber": {
      "type": [
        "string",
        "number"
      ],
      "description": "track_number of the MAIN track, as returned by km_search."
    },
    "libraryType": {
      "type": "string",
      "description": "Pass through library_type from the km_search result so web_url gets the right tier."
    }
  },
  "required": [
    "albumCode",
    "trackNumber"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

把用户手里的下载文件名、UPM 链接、本站链接（专辑 / 厂牌 / 选曲清单 / 歌单 / 搜索结果页）、外站链接或带连字符的专辑编号，定位成下一步可用的对象。 Resolves a download filename, UPM link, kindlemusic.cn link (album / label / pick list / playlist / search page), other web link or hyphenated album code into something the other km_* tools can act on. 何时用 / When: 用户贴的是 KM_PUC045_TK003_xxx.mp3、universalproductionmusic.com 链接、www.kindlemusic.cn/… 链接或 PUC-045 这类编号时，先调本工具；不要把它们当关键词丢进 km_search（会零结果）。 返回 / Returns: { q, resolved }。resolved 为 null 表示认不出或库里没有。按 kind 接下一步： - kind="track"，source 为 upm / filename（文件名 / UPM 链接）：{ albumCode, trackNumber（主曲曲号）, trackIdentity, trackTitle, albumTitle }。剪辑版文件名一律映射到主版本；接着用 km_track_versions(albumCode, trackNumber) 取全部版本，或 km_search(searchField="album", keyword=albumCode) 拿曲目 id。 - kind="album"，source="code"（编号）：{ albumCode, albumTitle }。接着用 km_search(searchField="album", keyword=albumCode)。 - source="site"（本站链接）： - kind="track" 带 trackId：trackId 就是曲目 id，可直接喂 km_similar_by_track；带 trackNumber（专辑页 ?trackNumber=）：可直接喂 km_track_versions(albumCode, trackNumber)。 - kind="album"：{ albumCode, trackId:null }，同上接 km_search(searchField="album")。 - kind="label"：{ includeLabels:[厂牌名] }，原样放进 km_search 的 includeLabels 按厂牌收窄。 - kind="resultSet"：{ code }，选曲清单（/picks/<code>），用 km_get_result_set(code) 读回。 - kind="playlist"：{ playlistId } 或 { shareType, shareCode }，网站歌单 / 歌单分享链接，MCP 没有读取歌单的工具，请让用户在网站打开，或说出想要的风格改用 km_search。 - kind="search"：{ tier, args }，网站搜索结果页的条件已还原成 km_search 入参，原样传给 km_search 即可复现用户看到的那次检索。 - kind="page"：本站首页 / 列表页 / 场景页 / 指南，没有可直接检索的对象。 - kind="keywords"，source="slug"（外站链接、或本站认不出的路径）：{ keyword }，取自链接里的搜索参数或最后一段路径；可作为 km_search 的关键词（含中文时带 expand="fast"，或改用 searchField="ai"）。视频网站链接通常取不出曲名，有参考音频请走 km_similar_by_audio。

{
  "type": "object",
  "properties": {
    "q": {
      "type": "string",
      "description": "The filename, link or album code exactly as the user gave it."
    }
  },
  "required": [
    "q"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

以曲库里一首已有曲目为锚点，找音频听感相似的曲目（向量检索，不是关键词）。 Audio-similarity search anchored on an existing catalog track (vector search, not keywords). 何时用 / When: 用户说"再来一些像这首的"，或你已经命中一首合适的曲目、想扩出一组候选时。 接力用法：对"七八分像"的曲目取相似 → 挑出更像的一首再取相似，两三轮通常就能逼近目标。 入参 / Args: id = km_search 返回的曲目 id（不是 track_identity），须是主版本。limit 默认 12，上限 50。 不认 partition（独立精选 / 环球UPM 分区）；要按 BPM / 时长 / 标签收窄，拿结果在本地筛。 返回 / Returns: { searchId, total, tracks[] }，曲目字段与 km_search 一致。 返回的 track_url 仅供试听/临时分析，见 audioNotice。 Returned track_url values are for audition / temporary analysis only; see audioNotice.

{
  "type": "object",
  "properties": {
    "id": {
      "type": [
        "string",
        "number"
      ],
      "description": "Track id as returned by km_search (field \"id\")."
    },
    "limit": {
      "type": "integer",
      "minimum": 1,
      "description": "Default 12, clamped to 50."
    },
    "libraryType": {
      "type": "string"
    }
  },
  "required": [
    "id"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}

按 code 读回一份已发布的选曲清单（含分段、曲目与每首的状态）。 Reads back a published pick list by its code, including sections, tracks and each track status. 何时用 / When: 用户要在既有清单上继续增删改，或要确认清单里的曲目是否仍在架。 返回 / Returns: 清单全文；已过期或已撤销时 sections 为空数组（看 expired / revoked 字段）。 返回的 track_url 仅供试听/临时分析，见 audioNotice。 Returned track_url values are for audition / temporary analysis only; see audioNotice.

{
  "type": "object",
  "properties": {
    "code": {
      "type": "string",
      "description": "The pick-list code returned by km_create_result_set."
    }
  },
  "required": [
    "code"
  ],
  "additionalProperties": false,
  "$schema": "http://json-schema.org/draft-07/schema#"
}