ITOSMPiano-BachToBasics/PROJECT_MEMORY.md

ITOSM Bach to Basics 프로젝트 기록

프로젝트 소속

• 서비스: ITOSM 피아노 학습실의 Bach to Basics 한국어판
• 공개 주소: https://learn.itosm.co.kr
• 운영 소스: /home/syskiller/piano/bach-to-basics
• Gitea 저장소: syskiller/ITOSMPiano-BachToBasics
• ITOSMGames와 game.itosm.co.kr에는 이 프로젝트 파일과 기록을 넣지 않는다.

2026-10-04 서비스 결정

• 피아노 학습 서비스의 최종 사용 프로그램은 Bach to Basics로 정했다.
• 포럼의 서비스 소개와 이용 안내는 https://learn.itosm.co.kr을 기준으로 구성한다.
• NoteRain은 최종 학습 서비스로 안내하지 않는다. 별도 종료 지시가 없으므로 기존 운영 상태 변경은 별도 작업으로 판단한다.
• Discourse 포럼 작업방에 소개와 용도별 게시 공간 구성을 요청했다. 실제 포럼 반영 결과는 해당 방에서 확인한다.

2026-10-09 초보자용 MIDI 연습곡

• 직접 만든 양손 피아노 연습곡 다섯 MIDI를 공개 곡 보관함에 추가했다. 별빛 계단은 입문과 쉬움 두 버전을 같은 제목 아래에서 선택한다. 나머지는 저녁빛 왈츠, 해돋이 아르페지오, 검은 건반 산책이다.
• 각 MIDI는 약 64~76초 길이다. 왼손 근음·5도 교대와 분산 화음 및 3박자 왈츠와 오른손 아르페지오와 검은 건반 5음 음계를 연습한다.
• 영상의 곡을 복제하지 않았다. 분산 화음과 아르페지오 기법 참고 강좌의 제작자와 링크를 docs/THIRD_PARTY_SAMPLES.md에 기록했다.
• python backend/tools/generate_beginner_midis.py로 파일을 재생성하고 node scripts/check_beginner_midis.mjs로 두 손 트랙과 길이 및 박자를 검사한다.
• 운영 DB와 수정 대상 소스의 백업은 /home/syskiller/piano/backups/bach-to-basics/20261009-beginner-midi에 있다. DB 변경은 서버 시작 시 새 기본 공개 곡 5건을 등록한 것뿐이며 회원 자료 이전은 없었다.
• 개발 환경에서 MIDI 파서 검사와 백엔드 단위 테스트 5개를 통과했다. 운영 HTTPS 첫 화면과 비회원 공개 목록 및 MIDI 파일 5개 다운로드를 확인했다. 기존 회원 업로드 2개를 보존했고 백엔드만 갱신했다. 프런트엔드는 재시작하지 않았다.
• 실제 USB MIDI 장치로 다섯 곡의 손별 따라치기를 확인하는 작업은 남아 있다.

2026-10-09 연습곡 30개 교체

• 위 다섯 곡은 선율이 지나치게 비슷하다는 의견을 반영해 공개 목록에서 제거했다. 해당 기본 자료의 파일과 생성 스크립트도 교체했다. 회원 업로드에는 손대지 않았다.
• Mutopia Project에 원본과 권리 정보가 함께 있는 서로 다른 피아노곡 30개를 골랐다. 부르크뮐러 Op. 100에서 18곡과 슈만 Op. 68에서 12곡이다. 도입부에는 각 원곡의 첫 선율을 천천히 제시하고 마무리에는 마지막 선율과 긴 종지음을 넣었다. 각 편곡은 69~134초다.
• 오른손의 중심 선율과 왼손 저음을 양손 연습용으로 정리했다. 오른손 음표 밀도에 따라 입문과 쉬움과 중급으로 분류했다. 원본 MIDI와 RDF 및 곡별 출처와 라이선스를 backend/tools/practice_sources와 backend/sample_midi/practice_collection.json에 보관한다. 슈만 자료의 CC BY-SA 버전은 편곡본에도 적용한다.
• node scripts/build_practice_collection.mjs로 파일을 다시 만들고 node scripts/check_practice_collection.mjs로 30개의 서로 다른 선율과 양손 트랙 및 도입부와 마무리와 길이를 검사한다. 서버의 격리 폴더에서 백엔드 단위 테스트 5개를 통과했다.
• 운영 DB와 수정 대상 소스 및 기존 MIDI 파일의 백업은 /home/syskiller/piano/backups/bach-to-basics/20261009-practice-30-intro-ending에 있다. 백엔드만 다시 빌드했고 프런트엔드는 재시작하지 않았다. 공개 HTTPS 첫 화면과 비회원 목록의 새 곡 30개 및 각 파일의 MIDI 다운로드를 확인했다. 기존 회원 업로드 2건은 유지됐다.
• 30곡은 공개 도메인 또는 CC BY-SA로 표시된 고전 연습곡의 편곡이다. 특정 한국 쇼츠의 곡을 전사한 자료는 아니다. 실제 피아노 건반으로 각 곡의 연주감과 MIDI 입력을 확인하는 작업은 남아 있다.

2026-10-09 연습곡 30개 철회

• 위 30곡은 사용자 요청과 맞지 않아 운영 공개 목록과 MIDI 파일 및 생성 자료에서 모두 제거했다. 회원 업로드와 기존 기본 샘플 7개는 변경하지 않았다.
• 재시작 후에도 다시 등록되지 않도록 해당 30개 파일명을 제외 목록에 넣었다. Git 기록은 다시 쓰지 않고 삭제를 새 커밋으로 남긴다.
• 철회 직전 DB와 30개 MIDI 및 원본·생성 자료의 백업은 /home/syskiller/piano/backups/bach-to-basics/20261009-withdraw-practice-30에 있다. 백엔드만 다시 빌드했다. 재시작 후 HTTPS 공개 목록 0건과 DB 0건 및 MIDI 파일 0개를 확인했다. 회원 업로드 2건과 기존 기본 샘플 7개는 보존됐다.

2026-10-03 현재 상태

• Docker의 piano-bach-frontend와 piano-bach-backend로 운영한다.
• 로그인과 회원 가입과 비밀번호 변경과 회원 탈퇴를 지원한다.
• 관리자 권한이 확인된 계정에만 관리자 패널 진입 버튼을 표시한다.
• 곡별 공개 범위와 최소 회원 등급과 지정 회원 공유를 지원한다.
• 보관함 업로드 형식은 MIDI와 MusicXML과 MXL 및 PDF다.
• 공개 샘플은 Mutopia Project 공개 도메인 자료와 그 단계별 연습 편곡 7개다.
• 악보 표시에는 AlphaTab과 Bravura SMuFL 글꼴을 사용한다.
• MIDI 변환 악보에서 C6 이상의 연속 고음은 8va로 표시한다. C2 이하의 연속 저음은 8vb로 표시해 덧줄을 줄인다. 실제 재생 음높이는 바꾸지 않는다.
• 화면과 브라우저 제목의 서비스 이름은 ITOSM 피아노 학습실이다. 왼쪽 위 표식과 설정 화면은 전용 음표 표식을 사용하며 서비스 Gitea 저장소로 연결한다.

확인된 운영 결과

• 기존 회원 업로드 20360.mid는 보글보글이라는 제목으로 보존돼 있다.
• 엘리제를 위하여는 입문과 쉬움과 고급 3개 버전으로 묶여 표시된다.
• 두 미뉴에트는 각각 단순화한 양손 연습과 양손 원곡 2개 버전으로 묶여 표시된다.
• 단계별 공개 샘플은 모두 오른손과 왼손을 포함한 피아노 독주다. 손별 연습은 연습 화면에서 선택한다.
• 곡 목록 조회는 일시적인 연결 실패 때 한 번 재시도한다. 정상 응답을 받으면 남아 있던 연결 오류를 지운다.
• 악보 커서는 변환된 악보의 시간 위치와 원본 템포 지도를 환산한 AlphaTab tick을 함께 사용한다. 음소거된 내부 플레이어가 위치 이벤트를 보내지 않는 경우에도 악보 렌더가 끝나면 커서를 직접 갱신한다. 확인한 AlphaTab 1.8.3을 고정해 커서 경로 변경으로 인한 재발을 막는다.
• 전체 화면의 악보 영역은 높이의 38%를 사용한다. 최소 높이는 화면에 따라 150px에서 220px 사이로 조정한다. 악보 렌더링이 끝난 뒤 실제 높이를 측정하며 양손 보표가 영역을 넘으면 배율을 자동으로 낮춰 위아래가 잘리지 않게 한다.
• 운영 브라우저에서 미뉴에트와 엘리제를 위하여 입문 악보의 오선과 음표 표시를 확인했다.
• 운영 백엔드에서 MIDI와 MusicXML과 MXL 및 PDF 검증기를 모두 통과했다.
• 프런트 타입 검사와 70개 테스트와 운영 빌드를 통과했다.

백업

• 작업 전 DB와 수정 대상 소스: /home/syskiller/piano/backups/bach-to-basics/20261003-1545-sheet-upload
• 악보 영역 자동 맞춤 적용 전 소스: /home/syskiller/piano/backups/bach-to-basics/20261003-1730-sheet-fit

남은 확인

• 실제 회원 화면에서 MusicXML과 MXL 및 PDF 파일을 각각 업로드한 뒤 삭제하는 통합 검사를 추가로 수행한다.
• 실제 USB MIDI 피아노를 연결한 모바일 또는 태블릿 Chromium 환경에서 입력 지연과 따라치기 동작을 확인한다.