Global Chromatic Identity State

GCIS

The open harmonic state standard for music applications

One file. One format. Root, mode, scale, and active notes — portable across any music tool, any platform, any AI. Created by Benjamin Ryan · Keys, Codes & Modes™

▶ Validate a File ⬇ Download Examples 📖 Read the Spec
Why

Music tools don't speak the same language.
GCIS changes that.

Every DAW, every theory app, every AI music generator has its own internal state. GCIS is the universal envelope that lets them share a harmonic context instantly.

🎯
Single Source of Truth
Root, mode, scale intervals, and active MIDI notes in one validated JSON envelope. No ambiguity, no drift.
🔁
Portable Across Tools
Save a session in the KCM Console. Load it in Ableton, MuseScore, or any AI generator that reads GCIS. One click.
🏫
Built for Education
Teachers save harmonic contexts as .gcis files. Students load them and immediately see and hear the same musical state.
🤖
AI-Ready
GCIS gives AI music tools a structured harmonic prompt. "Generate in G Dorian" is now a file, not a guess.
✅
Validated at Format Level
The spec enforces KCM modal vocabulary. "major" is not a mode. "H" is not a note. The validator catches it instantly.
🔓
Human-Readable
Plain JSON. Open any .gcis file in a text editor and read it. Change the root by hand. Load it back. It just works.
Specification

GCIS v1.0 — File Format Reference

A .gcis file is a UTF-8 encoded JSON document with a versioned envelope. The state object is the canonical harmonic snapshot.

Complete example — G Dorian

      

      

        
Field reference

        

          
FieldTypeReqDescription

          
            
gcisstring✅Format version — always "1.0"

            
state.rootstring✅Pitch class — one of 12 valid values

            
state.modestring✅Modal name — one of 7 valid values

            
state.scaleint[]✅7 semitone intervals from root

            
state.activeNotesint[]✅MIDI note numbers — sorted, may be empty

            
titlestring—Human-readable session name

            
authorstring—Creator name

            
createdstring—ISO 8601 timestamp

            
appobject—Originating app: name, version, url

            
historyarray—Reserved — session recording (v1.1)

          
        

      

    

    

      
Valid Pitch Classes (state.root)

      

      
Sharp notation canonical. Enharmonic flats not accepted (use C# not Db).

    

    

      
Valid Modes (state.mode)

      

    

  






  

    
Validator

    
Validate a .gcis File

    
Drop a file, paste JSON, or click a test case. Get a full diagnostic readout instantly.

    

      

        

          
Input

          

            

              
              
⬆

              
Drop .gcis file or click to browse

            

            
            
            
          

        

        

          
Built-in Tests 

          

        

      

      

        
Diagnostic Readout

        
Drop a .gcis file or paste JSON
to see the diagnostic readout.

      

    

  






  

    
Downloads

    
Example .gcis Files

    
Download these to test your implementation or use as starting points. Each is a fully valid GCIS v1.0 document.

    

  






  

    
Implementors

    
Apps that speak GCIS

    
The reference implementation is the KCM Console. Want your app listed? Implement the spec, validate with the tool above, and get in touch.

    

      

        
        

          
KCM Console Reference Implementation

          
Save and load .gcis from the Console header. Three panels — Music Theory Pro, Circle of Fifths, Modal Stencil — all sync from a single .gcis file. console.keyscodesandmodes.com ↗

        

      

    

    

      
Building a GCIS-compatible app?

      Contact to get listed ↗