carnet

Modifier quelques champs d'une chanson

Modification PARTIELLE : seuls les champs PRESENTS bougent. Un champ absent n'est pas touche ; un champ a null efface la valeur (artist: null, key: null, capo: null, bpm: null).

key est la tonalite AFFICHEE, meme convention que la lecture et que l'export ChordPro : G (majeur), Am (mineur). Elle est decomposee vers detectedKey dans le payload pivot, puis recomposee a l'identique par la lecture.

playlistIds est l'etat CIBLE COMPLET des appartenances : la chanson est ajoutee aux playlists citees et RETIREE de toutes les autres. [] la sort de toutes ses playlists. Declaratif, donc idempotent. Une playlist inconnue ou appartenant a un autre compte rend le meme 404 indifferencie qu'une chanson inconnue.

PUBLICATION SUR LE PROFIL (doctrine sociale 3.0.0) : publish: true publie la chanson sur le profil de l'appelant, publish: false la retire. Trois regles, toutes appliquees par la base et non par cette API :

  • PUBLIER EXIGE UNE DECLARATION DE DROITS, une fois par objet : joindre publishDeclaration (created, imported_no_known_restriction ou arrangement). Sans elle, 409 declaration-required. Republier un objet deja declare ne la redemande pas ;
  • publier exige un profil public (un pseudo @handle choisi dans l'application), sinon 409 profile-required ;
  • pendant une suspension de partage, rien ne se publie (409 sharing-suspended).

DEPUBLIER (publish: false) n'a AUCUNE condition : retirer son contenu ne se negocie pas. La reponse porte alors published.

Publier ne monte PAS de bande-son : l'audio d'une chanson publiee ne s'ecoute qu'entre comptes qui se suivent mutuellement, et il est depose par l'application depuis l'appareil qui detient le fichier.

patch/me/songs/{songId}

Request

  • Base URL: https://jam-jam.org/api/v1
  • URL: https://jam-jam.org/api/v1/me/songs/{songId}
  • Auth: one of:
    • HTTP bearer
    • none

Path parameters

songIdstring required

Identifiant stable de la chanson au carnet (slug artiste-titre).

Headers

If-Matchstring

updatedAt ISO 8601 lu sur l'objet, avec ou sans guillemets ("2026-09-21T12:00:00.000Z" ou la forme nue). Si la valeur en base differe, l'ecriture est refusee par 409 conflict, dont le corps porte l'updatedAt serveur courant. Absent = dernier ecrivain gagne. If-Match: * n'est pas pris en charge (400).

Request body

titlestring
artiststring nullable
keystring nullable

Tonalite AFFICHEE (G, Am). null efface la tonalite.

capointeger nullable
bpminteger nullable
playlistIdsstring[]

Etat CIBLE COMPLET des appartenances (declaratif, idempotent).

publishboolean

true publie sur le profil (exige publishDeclaration a la premiere publication de cet objet, et un profil public) ; false depublie, sans condition.

publishDeclaration'created' | 'imported_no_known_restriction' | 'arrangement'

Declaration de droits, exigee UNE FOIS PAR OBJET a sa premiere publication. created : vous en etes l'auteur. imported_no_known_restriction : reprise dont vous ne connaissez aucune restriction. arrangement : votre agencement. Sans publish: true, ce champ est refuse (400).

Example request

{
  "key": "G"
}

Response

Chanson modifiee

idstring required

Identifiant stable de l'objet ecrit.

updatedAtstring date-time required

Horodatage serveur apres l'ecriture, en ISO 8601 UTC au millieme. C'est EXACTEMENT la valeur a renvoyer dans If-Match.

publishedboolean

Present UNIQUEMENT quand la requete portait publish : etat REEL de la publication apres l'ecriture. Un refus de publication n'est jamais un published: false silencieux, c'est un 409.

Changes

No recorded changes to this operation across all 1 revision of this API.