Le format funscript, champ par champ

La structure

Un funscript est un objet JSON enregistré en texte UTF-8 avec l'extension .funscript. Un petit fichier complet, sous la forme qu'enregistre AutoScript Sync :

{
  "version": "1.0",
  "inverted": false,
  "range": 100,
  "metadata": {
    "creator": "AutoScript Sync",
    "format": "funscript"
  },
  "actions": [
    {"at": 0,    "pos": 50},
    {"at": 350,  "pos": 95},
    {"at": 720,  "pos": 5},
    {"at": 1080, "pos": 95},
    {"at": 1500, "pos": 5},
    {"at": 5500, "pos": 5}
  ]
}

Les deux derniers points gardent la même position pendant quatre secondes : une pause s'écrit avec deux points au même pos, pas avec un trou. L'ordre des clés n'a pas d'importance en JSON, et les espaces sont libres.

Les champs

actions

Un tableau de points, chacun étant un objet avec at et pos. C'est le seul champ dont un lecteur a besoin. Un fichier sans lui n'est pas un script utilisable.

at

Le moment du point en millisecondes depuis le début de la vidéo, sous forme d'entier. 1500 correspond à une seconde et demie.

pos

La position à atteindre à ce moment, sous forme d'entier de 0 à 100. Ce que 0 et 100 signifient physiquement dépend de l'appareil et de ses réglages ; le fichier dit seulement « à tel point de l'amplitude ».

version

La version du format sous forme de chaîne, généralement "1.0".

inverted

true ou false. Si true, les positions doivent être lues à l'envers, comme 100 − pos.

range

Un nombre, généralement 100, qui décrit l'étendue de pos. La plupart des fichiers le laissent à 100.

metadata

Un objet pour tout ce qui concerne le script : le programme qui l'a créé, un titre, des notes, des tags. Les lecteurs n'en ont pas besoin pour jouer le fichier.

Les fichiers issus d'éditeurs contiennent souvent des clés supplémentaires au premier niveau, comme des chapitres ou des signets. Elles sont autorisées ; un lecteur qui ne les comprend pas doit les ignorer et, idéalement, les conserver.

Les conventions que suit un fichier bien formé

• at est un nombre entier de millisecondes, compté depuis le début de la vidéo, jamais négatif.
• pos est un nombre entier de 0 à 100.
• Les actions sont triées par at, de la plus ancienne à la plus récente.
• Deux actions ne partagent jamais le même at.
• Les nombres sont des nombres JSON, pas des chaînes : "at": 400, et non "at": "400".

Les programmes sont plus ou moins tolérants quand un fichier enfreint ces règles. L'application de bureau répare ce qu'elle peut, comme décrit ci-dessous. Notre propre outil dans le navigateur, Report Studio, ne le fait pas : il suppose que les actions sont déjà triées, prend la durée à partir de la dernière action, ignore inverted et range, et refuse un fichier dont les valeurs at sont des chaînes. Un fichier qui respecte les cinq conventions évite ces différences.

Comment AutoScript Sync lit un fichier

Quand vous ouvrez un script avec Load Funscript…, que vous le déposez sur la fenêtre, ou que vous ouvrez une vidéo accompagnée d'un script du même nom, l'application répare les actions au lieu de refuser le fichier :

• elle trie les actions par temps ;
• elle fusionne les actions qui ont le même temps, en gardant la dernière ;
• elle ramène pos dans 0–100 et les temps négatifs à 0 ;
• elle ignore les entrées qu'elle ne peut pas lire, sans dire combien ;
• elle lit range mais ne s'en sert jamais pour remettre à l'échelle, donc un fichier avec une plage autre que 100 est quand même traité comme 0–100 ;
• elle conserve version tel quel ("1.0" s'il manque).

La prochaine mise à jour (2.121.2, compilée mais pas encore publiée) permet au lecteur d'accepter plus de fichiers et de conserver davantage de leur contenu :

• les fichiers enregistrés avec une marque d'ordre des octets (BOM), ou en UTF-16, se chargent au lieu d'être refusés ;
• inverted: true est appliqué une fois au chargement (100 − pos), avec une note pour vous, et le fichier est réenregistré avec inverted: false, pour que tous les autres lecteurs voient le même mouvement. L'application publiée ignore cet indicateur, donc un fichier inversé est joué à l'envers ;
• les valeurs at et pos fractionnaires sont arrondies à l'entier le plus proche, et les valeurs NaN ou infinies sont ignorées ;
• les clés de premier niveau inconnues, comme les chapitres ou les signets, sont conservées et réécrites à l'enregistrement ; l'application publiée les supprime à l'enregistrement ;
• un fichier qui n'est pas du texte, pas du JSON, pas un objet ou qui n'a pas de liste actions reçoit un message en langage clair, et un script sans aucune action utilisable n'est pas associé à la vidéo.

Comment AutoScript Sync écrit un fichier

Chaque script que l'application enregistre, généré ou modifié, respecte les conventions ci-dessus, quoi qu'il se soit passé dans l'éditeur :

• Les actions sont écrites par ordre chronologique croissant, avec des temps uniques, at en nombre entier positif ou nul de millisecondes et pos en nombre entier de 0 à 100. Si deux points s'arrondissent à la même milliseconde, le plus tardif l'emporte.
• En-tête : version, inverted et range sont écrits tels qu'ils sont en mémoire ; un script généré reçoit "1.0", false et 100.
• Métadonnées : creator vaut toujours "AutoScript Sync" et format vaut "funscript". Enregistrer par-dessus le script d'un autre outil remplace son créateur.
• Détails d'analyse dans les scripts générés : générateur, résumé de reconnaissance, temps de traitement, chemin de suivi et un bloc ai contenant, pour chaque fenêtre de deux secondes, l'étiquette de type de scène, la région suivie, la part comblée plutôt que mesurée, et les scores d'élection du point d'ancrage.
• Enregistrement sûr : le JSON est écrit, indenté, dans un fichier temporaire puis substitué à l'original, pour qu'un plantage en cours d'enregistrement ne puisse pas corrompre le script existant.
• Sauvegarde : quand Generate enregistre à côté de la vidéo, tout script existant est d'abord copié vers <name>.funscript.bak. Une seule sauvegarde est conservée ; le Generate suivant l'écrase.

Le fichier sur le disque n'est jamais adapté à un appareil. Quand l'application envoie un script à l'Autoblow AI Ultra, elle adapte une copie aux limites de l'appareil et retire les métadonnées d'analyse, en ne gardant que le mouvement et quelques champs d'en-tête (generator, creator, format, version, range, stroke_expansion et un id s'il existe).

Questions

À lire ensuite

• Vérifier un fichier avec le validateurTrouve dans votre navigateur les erreurs décrites sur cette page, et propose une copie réparée.
• Une introduction en langage clairCe qu'est un funscript et comment un appareil l'utilise, sans le détail des champs.
• Créer un funscript, à la main ou généréLe processus, de la vidéo au fichier enregistré et vérifié.
• Le centre d'apprentissageLes quatre pages de référence.