@ihabdevteam/core 0.124.0 → 0.126.0

package/dist/ihabdevteam-core.d.ts

@@ -1341,7 +1341,7 @@ export declare function copyText(text: string): Promise<boolean>;
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.124.0";
+export declare const CORE_VERSION = "0.126.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -1363,13 +1363,13 @@ export declare type CoreNoiseSettings = {
     level: number;
     /**
      * 소음 비율 — 문제 소리 대비 소음의 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
-     * 문제 소리 = mainVolume × min(1, 1/noiseRatio), 소음 = mainVolume × min(1, noiseRatio).
+     * 문제 소리 = mainVolume, 소음 들리는 크기 = mainVolume × noiseRatio(원본 소음 파일 기준).
      * 없으면 `level` 에서 옮긴다.
      */
     noiseRatio?: number;
     /** 소음 재생 속도(playbackRate). 0.75–1.25, 기본 1. */
     speed: number;
-    /** 전체 소리 — 두 소리 중 큰 쪽의 크기. 0–1, 기본 1. 실제 두 볼륨은 `noiseRatio` 로 나뉜다. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
+    /** 전체 소리 = 문제 소리 볼륨. 0–1, 기본 1. 소음은 이 값 × `noiseRatio`. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
     mainVolume: number;
     /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
     mainSpeed: number;
@@ -1417,6 +1417,8 @@ export declare type CoreScopeStorageConfig = {
      * @example 'https://cdn.example.com/sounds/noise'
      */
     noiseBaseUrl?: string;
+    /** (선택) 소음 파일이 원본보다 몇 배 큰지(진폭). 기본 1 — configureStorage 의 같은 이름 참고. */
+    noiseFileGain?: number;
 };
 
 /**
@@ -2221,11 +2223,15 @@ export declare function getDailySelection(): {
 };
 
 /**
- * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
- * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ * 엘리먼트에 연결된 AnalyserNode 를 반환(달리는 컨텍스트면 지금 태워서).
+ * 컨텍스트가 suspended 면 **지금은 null** 을 주고 resume 뒤 태우기를 걸어 둔다 — 나중 값이 필요하면
+ * `routeElementAudio` 를 기다린다. 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
  */
 export declare function getElementAnalyser(el: HTMLMediaElement | null | undefined): AnalyserNode | null;
 
+/** @public 요소에 걸려고 한 볼륨(0~1) — 램프 출발점. 건 적이 없으면 요소 volume. */
+export declare function getElementVolume(el: HTMLMediaElement): number;
+
 /**
  * 잡은 값에서 **사람이 읽을 수 있는 원인**을 꺼낸다.
  *
@@ -2269,6 +2275,12 @@ export declare function getImageResolver(): ((word: string, homonum?: number) =>
  */
 export declare function getNoiseBaseUrl(): string;
 
+/**
+ * 소음 파일이 원본보다 몇 배 큰지 — configureStorage 의 noiseFileGain. 없거나 양수가 아니면 1.
+ * @public
+ */
+export declare function getNoiseFileGain(): number;
+
 /** @public 현재 메모리에 적재된 인덱스 (없으면 localStorage 시도) */
 export declare function getPairIndex(): PairIndex | null;
 
@@ -4646,14 +4658,20 @@ export declare function resolveTrainingPopupMeta(trainingData: Record<string, un
 };
 
 /**
- * 오디오 레벨 미터용 Web Audio 유틸.
+ * 오디오 레벨 미터 + 볼륨용 Web Audio 유틸.
  *
- * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
- * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
- * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
- *   source를 analyser와 destination 양쪽에 연결한다.
- * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
- *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ * HTMLMediaElement 를 한 그래프에 태운다: `source → GainNode → (AnalyserNode, destination)`.
+ * - createMediaElementSource 는 엘리먼트당 1회만 가능 → WeakMap 으로 캐싱.
+ * - **볼륨은 GainNode 로 건다**(0.126.0). 실제 iPhone·iPad 에서는 `HTMLMediaElement.volume` 을
+ *   스크립트로 바꿔도 소리에 안 먹는다(Apple 문서 — 늘 1). 그래프에 태운 요소는 volume 을 1 로
+ *   두고 `gain` 으로 크기를 정하므로 기기와 상관없이 먹는다. 미터(analyser)는 gain 뒤라 들리는
+ *   크기를 읽는다(요소 volume 이 소스 출력에 걸리던 전과 같은 결).
+ * - **달리는(running) AudioContext 에만 태운다.** 태운 순간부터 요소 소리는 destination 연결로만
+ *   나가므로, suspended(자동재생 정책) 컨텍스트에 태우면 resume 전까지 무음이다. 그래서 suspended
+ *   이면 resume 이 끝난 뒤에 태우고, 그 전에는 요소가 제 볼륨으로 직접 울린다.
+ * - Web Audio 가 없거나 태우기에 실패하면(미지원·이미 다른 그래프에 소스됨 등) 요소 volume 으로 물러선다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous" 가 있고 서버가 CORS 를 허용해야 그래프
+ *   출력이 무음이 되지 않는다(코어의 문장·소음 요소는 둘 다 붙인다).
  */
 /** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
 export declare function resumeAudioMeter(): void;
@@ -4786,6 +4804,14 @@ export declare interface RingChartSegment {
 /** 시맨틱 사이즈 → 지름(px)·링 두께(px) 프리셋 */
 export declare type RingChartSize = 'small' | 'medium' | 'large';
 
+/**
+ * 엘리먼트를 그래프에 태우고 AnalyserNode 를 준다(이미 태웠으면 그것).
+ * 컨텍스트가 suspended 면 resume 을 기다린 뒤 태운다 — resume 이 안 되면(제스처 없음) null 이고
+ * 요소는 제 볼륨으로 계속 울린다. Web Audio 미지원·실패도 null.
+ * @public
+ */
+export declare function routeElementAudio(el: HTMLMediaElement | null | undefined): Promise<AnalyserNode | null>;
+
 /**
  * @public 배열에서 무작위로 최대 n개를 뽑아 새 배열로 반환(원본 불변).
  * n이 길이 이상이면 전체를 셔플해 반환한다.
@@ -5089,6 +5115,13 @@ export declare function setAssetBaseUrl(baseUrl?: string | null): void;
 /** @public */
 export declare function setCrosswordLogger(fn: CrosswordLogger | null): void;
 
+/**
+ * @public 요소 볼륨(0~1)을 건다. 그래프에 태운 요소면 요소 volume 은 1 로 두고 GainNode 에
+ * (짧은 시정수로 매끄럽게) 걸고 'gain', 아니면 요소 volume 에 걸고 'element'. 부르는 쪽이 매 프레임
+ * 불러 램프를 만들어도 된다.
+ */
+export declare function setElementVolume(el: HTMLMediaElement, volume: number): 'gain' | 'element';
+
 /** @public */
 export declare function setGameLeaderboardLoader(fn: LeaderboardFn): void;
 
@@ -5650,6 +5683,16 @@ export declare interface StorageResolvers {
      * @example 'https://cdn.example.com/sounds/noise'
      */
     noiseBaseUrl?: string;
+    /**
+     * (선택) `noiseBaseUrl` 의 소음 파일이 **원본 소음보다 몇 배 큰지**(진폭). 기본 1.
+     *
+     * 소음 비율 R 은 원본 파일 기준이라 `<audio>` 볼륨 = min(1, 전체 소리 × R ÷ 이 값) 이다.
+     * 볼륨은 1 을 넘을 수 없으므로 원본 파일로는 1배 넘는 소음이 1 에서 멈춘다 — 2배로 키운 파일과
+     * `noiseFileGain: 2` 를 함께 주면 0~2배가 정확히 들린다.
+     *
+     * @example 2
+     */
+    noiseFileGain?: number;
 }
 
 /** @public */

package/dist/packages/core/src/CoreScope.d.ts

@@ -20,6 +20,8 @@ export type CoreScopeStorageConfig = {
      * @example 'https://cdn.example.com/sounds/noise'
      */
     noiseBaseUrl?: string;
+    /** (선택) 소음 파일이 원본보다 몇 배 큰지(진폭). 기본 1 — configureStorage 의 같은 이름 참고. */
+    noiseFileGain?: number;
 };
 /** @public */
 export type CoreScopeProps = {

package/dist/packages/core/src/CoreScope.js

@@ -11,6 +11,7 @@ export function CoreScope({ as: Component = 'div', className = '', children, sto
             exists: storage.exists,
             resolvePath: storage.resolvePath,
             noiseBaseUrl: storage.noiseBaseUrl,
+            noiseFileGain: storage.noiseFileGain,
         });
     }
     const classes = cx('ihabdevteam-core-scope', className);

package/dist/packages/core/src/components/AudioMeter.js

@@ -1,8 +1,8 @@
 'use client';
 import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { cx } from '../utils/cx';
-import { useEffect, useRef } from 'react';
-import { getElementAnalyser, resumeAudioMeter, readLevel } from '../utils/audioMeter';
+import { useEffect, useRef, useState } from 'react';
+import { getElementAnalyser, resumeAudioMeter, readLevel, routeElementAudio } from '../utils/audioMeter';
 import './AudioMeter.css';
 // 레벨 표시 평활화(빠른 어택 / 느린 릴리스)
 const RELEASE = 0.86;
@@ -27,14 +27,22 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
     const fillRef = useRef(null);
     const valueRef = useRef(null);
     const rafRef = useRef(null);
+    /* 컨텍스트가 아직 suspended 면 getElementAnalyser 는 지금 null 을 준다(달리는 컨텍스트에만 태운다 —
+       audioMeter 머리말). resume 뒤 태워지면 그 노드로 다시 돈다. */
+    const [routed, setRouted] = useState(null);
     useEffect(() => {
-        const node = analyser ?? getElementAnalyser(audioElement);
+        const node = analyser ?? getElementAnalyser(audioElement) ?? (routed && routed.el === audioElement ? routed.node : null);
         const fill = fillRef.current;
         if (!node || !fill) {
             fill?.style.setProperty('--meter-level', '0');
             if (valueRef.current)
                 valueRef.current.textContent = formatRelDb(floorDb, refDb, displayMin, displayMax);
-            return;
+            let cancelled = false;
+            if (!analyser && audioElement) {
+                void routeElementAudio(audioElement).then((n) => { if (!cancelled && n)
+                    setRouted({ el: audioElement, node: n }); });
+            }
+            return () => { cancelled = true; };
         }
         resumeAudioMeter();
         const buffer = new Float32Array(node.fftSize);
@@ -78,7 +86,7 @@ export default function AudioMeter({ analyser, audioElement, orientation = 'hori
                 cancelAnimationFrame(rafRef.current);
             rafRef.current = null;
         };
-    }, [analyser, audioElement, floorDb, refDb, displayMin, displayMax]);
+    }, [analyser, audioElement, routed, floorDb, refDb, displayMin, displayMax]);
     const lengthCss = typeof length === 'number' ? `${length}px` : length;
     const isVertical = orientation === 'vertical';
     const trackStyle = lengthCss

package/dist/packages/core/src/components/Training/NoisePlayerContext.d.ts

@@ -21,10 +21,18 @@ export declare function noiseRatioOf(settings: Pick<CoreNoiseSettings, 'level' |
 type 비율설정 = Pick<CoreNoiseSettings, 'level' | 'mainVolume'> & {
     noiseRatio?: number;
 };
-/** @public 실제 소음 볼륨(0~1) = mainVolume × min(1, 비율). 켜짐 여부는 보지 않는다. */
-export declare function effectiveNoiseVolume(settings: 비율설정): number;
-/** @public 실제 문제 소리 볼륨(0~1) = mainVolume × min(1, 1/비율). 비율 0 이면 mainVolume. */
+/** @public 문제 소리 볼륨(0~1) = mainVolume. 비율과 상관없다. */
 export declare function effectiveSpeechVolume(settings: 비율설정): number;
+/**
+ * @public 소음이 **들리는 크기**(0~2, 원본 소음 파일 기준) = mainVolume × 비율. 켜짐 여부는 보지
+ * 않는다. 결과 기록·파형이 쓴다. 소음 `<audio>` 에 거는 값은 `noiseElementVolume`.
+ */
+export declare function effectiveNoiseVolume(settings: 비율설정): number;
+/**
+ * @public 소음 `<audio>` 볼륨(0~1) = min(1, 들리는 크기 ÷ gain). gain 은 소음 파일이 원본보다 몇 배
+ * 큰지 — 기본은 `configureStorage({ noiseFileGain })`(없으면 1).
+ */
+export declare function noiseElementVolume(settings: 비율설정, gain?: number): number;
 /**
  * @public 설정에 조각을 덮는다 — `{ ...base, ...patch }` 에 비율 규칙 하나를 더한 것.
  *
@@ -32,8 +40,8 @@ export declare function effectiveSpeechVolume(settings: 비율설정): number;
  * 옛 `noiseOverride`). 그대로 덮으면 base 의 `noiseRatio`(기본값 1 등)가 남아 level 을 가려
  * 버리므로, 덮은 결과의 level·mainVolume 으로 비율을 셈해 **그 자리에서 박아 둔다** —
  * 박지 않고 비워 두면 뒤에 전체 소리만 바꿀 때 비율이 따라 변해 소음이 옛날처럼 제자리에 선다.
- * 비율이 1 을 넘으면 소음이 큰 쪽이므로 `mainVolume` 도 level/9 로 함께 박는다(옛날에 들리던
- * 두 크기 그대로 — 예: level 9·mainVolume 0.5 → 비율 2·mainVolume 1 = 소음 1·문제 0.5).
+ * `mainVolume` 은 그대로다 — 옛 뜻(문제 소리 = mainVolume, 소음 = level/9)이 새 셈(문제 = M, 소음 = M×R)
+ * 에서 들리던 크기 그대로 남는다(0.123.0 의 "R>1 이면 mainVolume = level/9" 는 0.125.0 에서 걷음).
  * `{ ...DEFAULT_NOISE_SETTINGS, ...saved }` 대신 이것을 쓴다.
  */
 export declare function mergeNoiseSettings(base: CoreNoiseSettings, patch?: Partial<CoreNoiseSettings> | null): CoreNoiseSettings;
@@ -50,7 +58,7 @@ export type NoisePlayerContextValue = {
     /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. */
     playbackRate: number;
     setPlaybackRate: (rate: number) => void;
-    /** 전체 소리 — 두 소리(문제 소리·소음) 중 큰 쪽의 크기. 0–1, 기본 1. 실제 볼륨은 effectiveSpeechVolume·effectiveNoiseVolume. */
+    /** 전체 소리 = 문제 소리 볼륨. 0–1, 기본 1. 소음은 이 값 × 소음 비율(noiseElementVolume 참고). */
     mainVolume: number;
     setMainVolume: (v: number) => void;
 };

package/dist/packages/core/src/components/Training/NoisePlayerContext.js

@@ -1,5 +1,6 @@
 'use client';
 import { createContext, useContext } from 'react';
+import { getNoiseFileGain } from '../../utils/storage';
 // 소음 크기: 내부 level(0~9 연속) ↔ 표시 percent(0~100). 소음 설정 툴팁과 계정 설정("훈련" 패널)이
 // 동일한 매핑을 써야 하므로 여기서 한 번만 정의해 공유한다.
 // 소음 음원 파일을 클리핑 없는 한도(+7dB, 약 2.24배)까지 증폭한 뒤 맞춘 상한값 —
@@ -11,15 +12,16 @@ export const levelToPct = (level) => Math.round((Math.min(LEVEL_MAX, Math.max(0,
 /** @public */
 export const pctToLevel = (pct) => (pct / 100) * LEVEL_MAX;
 /* ── 소음 비율 ──────────────────────────────────────────────────────────────
-   전체 소리(`mainVolume` 0~1)는 **두 소리 중 큰 쪽의 크기**이고, 소음은 문제 소리에 대한
-   **비율**(`noiseRatio` R, 0~2배)로 정한다.
-     R ≤ 1: 문제 소리 = M,     소음 = M × R
-     R > 1: 문제 소리 = M ÷ R, 소음 = M
-   곧 문제 소리 = M × min(1, 1/R), 소음 = M × min(1, R) — 어느 쪽도 1 을 넘지 않고, 0~2배가
-   전체 소리와 무관하게 정확히 들린다.
-   (0.120.0 에서는 문제 소리 = M, 소음 = min(1, M×R) 이라 M 이 50% 를 넘으면 소음이 1 에 막혀
-   슬라이더 배수와 실제가 어긋났다 — 전체 80% 에 2배 → 실제 1.25배. 0.123.0 에서 고침.)
-   예전(0.119.0 까지)에는 소음 크기(level/9)가 전체 소리와 따로 움직였다. */
+   전체 소리 M(`mainVolume` 0~1) = **문제 소리**. 소음은 문제 소리에 대한 **비율** R(`noiseRatio` 0~2배).
+     문제 소리          = M                     — 비율과 상관없이 줄이지 않는다
+     소음 들리는 크기   = M × R (0~2)           — **원본 소음 파일 기준**
+     소음 <audio> 볼륨  = min(1, M × R ÷ gain)  — gain = 소음 파일이 원본보다 몇 배 큰지
+                                                 (configureStorage 의 noiseFileGain, 기본 1)
+   <audio> 볼륨은 1 을 넘을 수 없어 원본 파일로는 1배 넘는 소음이 1 에서 멈춘다. 2배로 키운 파일
+   (gain 2)을 주면 0~2배가 정확히 들린다. 기본 gain 1 인 앱은 1배 초과만 1 에서 멈춘다.
+   0.120.0: 문제 = M, 소음 = min(1, M×R) — M 이 크면 1 에 막힘.
+   0.123.0: 문제 = M×min(1,1/R), 소음 = M×min(1,R) — 1~2배를 올려도 소음은 안 커지고 문제 소리만
+   줄었다(말귀 사용자). 0.125.0 에서 키운 파일로 푼다. */
 /** @public 소음 비율 상한(배). */
 export const NOISE_RATIO_MAX = 2;
 /** @public 소음 비율 칸(배). */
@@ -41,29 +43,25 @@ export function noiseRatioOf(settings) {
         return 1;
     return 한칸반올림(비율자르기(소음 / 전체));
 }
+const 전체소리 = (settings) => Math.min(1, Math.max(0, Number(settings.mainVolume) || 0));
+/** @public 문제 소리 볼륨(0~1) = mainVolume. 비율과 상관없다. */
+export function effectiveSpeechVolume(settings) {
+    return 전체소리(settings);
+}
 /**
- * 전체 소리와 비율을 확정한다. `noiseRatio` 가 없는 옛 기록은 옛 뜻(문제 소리 = mainVolume,
- * 소음 = level/9)이 **들리던 크기 그대로** 남도록 옮긴다 — R = noiseRatioOf, 그리고 R > 1 이면
- * 소음이 큰 쪽이므로 전체 소리 = level/9.
+ * @public 소음이 **들리는 크기**(0~2, 원본 소음 파일 기준) = mainVolume × 비율. 켜짐 여부는 보지
+ * 않는다. 결과 기록·파형이 쓴다. 소음 `<audio>` 에 거는 값은 `noiseElementVolume`.
  */
-function 확정(settings) {
-    const 전체 = Math.min(1, Math.max(0, Number(settings.mainVolume) || 0));
-    const noiseRatio = noiseRatioOf(settings);
-    const 옛기록 = !(typeof settings.noiseRatio === 'number' && Number.isFinite(settings.noiseRatio));
-    if (옛기록 && noiseRatio > 1) {
-        return { mainVolume: Math.min(LEVEL_MAX, Math.max(0, Number(settings.level) || 0)) / LEVEL_MAX, noiseRatio };
-    }
-    return { mainVolume: 전체, noiseRatio };
-}
-/** @public 실제 소음 볼륨(0~1) = mainVolume × min(1, 비율). 켜짐 여부는 보지 않는다. */
 export function effectiveNoiseVolume(settings) {
-    const { mainVolume, noiseRatio } = 확정(settings);
-    return mainVolume * Math.min(1, noiseRatio);
+    return 전체소리(settings) * noiseRatioOf(settings);
 }
-/** @public 실제 문제 소리 볼륨(0~1) = mainVolume × min(1, 1/비율). 비율 0 이면 mainVolume. */
-export function effectiveSpeechVolume(settings) {
-    const { mainVolume, noiseRatio } = 확정(settings);
-    return noiseRatio > 1 ? mainVolume / noiseRatio : mainVolume;
+/**
+ * @public 소음 `<audio>` 볼륨(0~1) = min(1, 들리는 크기 ÷ gain). gain 은 소음 파일이 원본보다 몇 배
+ * 큰지 — 기본은 `configureStorage({ noiseFileGain })`(없으면 1).
+ */
+export function noiseElementVolume(settings, gain = getNoiseFileGain()) {
+    const g = Number.isFinite(gain) && gain > 0 ? gain : 1;
+    return Math.min(1, effectiveNoiseVolume(settings) / g);
 }
 /**
  * @public 설정에 조각을 덮는다 — `{ ...base, ...patch }` 에 비율 규칙 하나를 더한 것.
@@ -72,16 +70,14 @@ export function effectiveSpeechVolume(settings) {
  * 옛 `noiseOverride`). 그대로 덮으면 base 의 `noiseRatio`(기본값 1 등)가 남아 level 을 가려
  * 버리므로, 덮은 결과의 level·mainVolume 으로 비율을 셈해 **그 자리에서 박아 둔다** —
  * 박지 않고 비워 두면 뒤에 전체 소리만 바꿀 때 비율이 따라 변해 소음이 옛날처럼 제자리에 선다.
- * 비율이 1 을 넘으면 소음이 큰 쪽이므로 `mainVolume` 도 level/9 로 함께 박는다(옛날에 들리던
- * 두 크기 그대로 — 예: level 9·mainVolume 0.5 → 비율 2·mainVolume 1 = 소음 1·문제 0.5).
+ * `mainVolume` 은 그대로다 — 옛 뜻(문제 소리 = mainVolume, 소음 = level/9)이 새 셈(문제 = M, 소음 = M×R)
+ * 에서 들리던 크기 그대로 남는다(0.123.0 의 "R>1 이면 mainVolume = level/9" 는 0.125.0 에서 걷음).
  * `{ ...DEFAULT_NOISE_SETTINGS, ...saved }` 대신 이것을 쓴다.
  */
 export function mergeNoiseSettings(base, patch) {
     const merged = { ...base, ...(patch ?? {}) };
     if (patch && 'level' in patch && !(typeof patch.noiseRatio === 'number')) {
-        const 박을것 = 확정({ level: merged.level, mainVolume: merged.mainVolume });
-        merged.noiseRatio = 박을것.noiseRatio;
-        merged.mainVolume = 박을것.mainVolume;
+        merged.noiseRatio = noiseRatioOf({ level: merged.level, mainVolume: merged.mainVolume });
     }
     return merged;
 }

package/dist/packages/core/src/components/Training/TrainingStepAudioPlayer.js

@@ -6,7 +6,7 @@ import { useTranslation } from "react-i18next";
 // TrainingItem, TrainingGroup import 제거됨 (resolveMapping 제거로 불필요)
 import { downloadSound, getSignedOrPublicUrl, resolveSoundPath } from '../../utils/storage';
 import { getTTSUrlResolver } from '../../utils/ttsConfig';
-import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
+import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume } from '../../utils/audioMeter';
 import { useNoisePlayer, effectiveNoiseVolume, effectiveSpeechVolume, noiseRatioOf } from './NoisePlayerContext';
 import { useNoiseFade } from './useNoiseFade';
 import { useTTSPlayback } from './useTTSPlayback';
@@ -97,10 +97,10 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     // 문장(메인) 재생 속도·볼륨 — 하단 소음설정 툴팁과 공유(NoisePlayerContext)
     const playbackRate = noisePlayer?.playbackRate ?? 1.0;
     const mainVolume = noisePlayer?.mainVolume ?? 1.0;
-    // 실제 두 볼륨 — 전체 소리(큰 쪽 크기)를 소음 비율로 나눈다(소리용). 파형은 M·R 로 따로 그린다.
+    // 문제 소리 = 전체 소리. noiseVolume 은 소음이 들리는 크기(M×R, 원본 파일 기준) — 0 이면 소음 파형을 안 그린다.
+    // 소음 <audio> 볼륨(파일 gain 으로 나눈 값)은 useNoiseFade 가 건다.
     const noiseVolume = noisePlayer ? effectiveNoiseVolume(noisePlayer.settings) : 0;
-    // 소음을 끈 판(소음 종류 "없음")은 들리지 않는 소음에 문제 소리를 양보하지 않는다 — 전체 소리 그대로.
-    const speechVolume = noisePlayer?.settings.enabled ? effectiveSpeechVolume(noisePlayer.settings) : mainVolume;
+    const speechVolume = noisePlayer ? effectiveSpeechVolume(noisePlayer.settings) : mainVolume;
     const [fillCompletionPhase, setFillCompletionPhase] = useState('idle');
     const [noticeMessage, setNoticeMessage] = useState("");
     const [noticePosition] = useState("top");
@@ -143,7 +143,7 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const { startTTS, stopTTS } = useTTSPlayback({
         ttsText,
         playbackRate,
-        // TTS 음성 = 문제 소리 — 전체 소리가 아니라 비율로 나뉜 문제 소리 볼륨
+        // TTS 음성 = 문제 소리 = 전체 소리
         mainVolume: speechVolume,
         fillRef,
         waveProgressRef,
@@ -204,10 +204,14 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             setStateLocal("playMode");
             set구간표시(true);
             startTicker();
-            // 미터: 재생 제스처 시점에 context resume 후 메인 analyser 등록(무음 방지)
+            // 문장을 Web Audio 그래프(gain·미터)에 태운다 — 재생 제스처 시점에 resume, 컨텍스트가 달리고 나서야
+            // 태우므로 그 전엔 요소가 제 볼륨으로 직접 울린다(무음 방지). 태운 뒤 볼륨은 GainNode 로 걸린다.
             try {
                 resumeAudioMeter();
-                registerAnalyserRef.current?.('main', getElementAnalyser(a));
+                void routeElementAudio(a).then((an) => { try {
+                    registerAnalyserRef.current?.('main', an);
+                }
+                catch (e) { } });
             }
             catch (e) { }
             // 소음 동기 시작
@@ -950,8 +954,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         }
         catch (e) { }
     }, [playbackRate]);
-    // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume). 전체 소리·소음 비율 어느 쪽을
-    // 바꿔도 달라진다. 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
+    // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume = 전체 소리). setElementVolume 이 그래프에 태운
+    // 요소면 GainNode, 아니면 요소 volume 에 건다(iOS 실기기는 요소 volume 이 안 먹는다). 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
     // 백그라운드 탭에서는 RAF 가 멈춰 램프가 중간에 설 수 있으므로 끝값을 타이머로 한 번 더 박는다.
     const speechRampRef = useRef({ raf: null, timer: null });
     useEffect(() => {
@@ -971,10 +975,10 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
             }
         };
         끊기();
-        const from = a.volume;
+        const from = getElementVolume(a);
         if (a.paused || Math.abs(from - target) < 0.001 || typeof requestAnimationFrame !== 'function') {
             try {
-                a.volume = target;
+                setElementVolume(a, target);
             }
             catch (e) { }
             return;
@@ -983,14 +987,14 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         const step = () => {
             const t = Math.min(1, (performance.now() - start) / 150);
             try {
-                a.volume = from + (target - from) * t;
+                setElementVolume(a, from + (target - from) * t);
             }
             catch (e) { }
             ramp.raf = t < 1 ? requestAnimationFrame(step) : null;
         };
         ramp.raf = requestAnimationFrame(step);
         ramp.timer = setTimeout(() => { 끊기(); try {
-            a.volume = target;
+            setElementVolume(a, target);
         }
         catch (e) { } }, 200);
         return 끊기;

package/dist/packages/core/src/components/Training/useNoiseFade.js

@@ -1,8 +1,8 @@
 'use client';
 import { useCallback, useEffect, useRef, useState } from 'react';
 import { noiseAssets } from '../../sounds/noiseAssets';
-import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
-import { effectiveNoiseVolume } from './NoisePlayerContext';
+import { resumeAudioMeter, routeElementAudio, setElementVolume, getElementVolume } from '../../utils/audioMeter';
+import { noiseElementVolume } from './NoisePlayerContext';
 function generateNoiseUrl(type) {
     const rand = Math.floor(Math.random() * 10);
     switch (type) {
@@ -24,7 +24,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
     // 실제 로드된(재생되는) 소음 파일 URL — waveform이 화면=청취 일치하도록 이 src를 그린다.
     const [activeNoiseUrl, setActiveNoiseUrl] = useState(null);
     const noiseTypeLoadedRef = useRef(null);
-    // volume = 실제 소음 볼륨(effectiveNoiseVolume — 전체 소리 × 소음 비율, 상한 1)
+    // volume = 소음 <audio> 볼륨(noiseElementVolume — 전체 소리 × 소음 비율 ÷ 파일 gain, 상한 1)
     const noiseSettingsRef = useRef(null);
     const noiseFadeRafRef = useRef(null);
     // 페이드 세대 토큰 — 하드스톱 타이머가 발화 시점에 "그 사이 새 페이드가 시작됐는지"를
@@ -47,24 +47,28 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             return;
         noiseFadeTokenRef.current += 1;
         cancelNoiseFade();
-        // 미터: 소음 재생 시점에 context resume 후 소음 analyser 등록
+        // 소음을 Web Audio 그래프(gain·미터)에 태운다 — 컨텍스트가 달리고 나서야 태우므로 그 전엔 요소가 직접 울린다.
+        // 볼륨은 setElementVolume 이 그래프면 GainNode, 아니면 요소 volume 에 건다(iOS 실기기는 요소 volume 이 안 먹는다).
         try {
             resumeAudioMeter();
-            registerAnalyserRef.current?.('noise', getElementAnalyser(noiseEl));
+            void routeElementAudio(noiseEl).then((an) => { try {
+                registerAnalyserRef.current?.('noise', an);
+            }
+            catch (e) { } });
         }
         catch (e) { }
         // 이미 재생 중이면(멀티소스 연달아 재생 — 단어1→단어2 전환마다 onPlay가 다시 호출됨)
         // 볼륨을 0으로 리셋하지 않고 현재 볼륨에서 목표까지 부드럽게 이어간다 — 트랙 전환 때마다
         // 소음이 뚝 끊겼다 다시 차오르던 문제 방지. 이미 목표 볼륨이면 램프가 사실상 no-op이다.
-        const startVol = noiseEl.paused ? 0 : noiseEl.volume;
+        const startVol = noiseEl.paused ? 0 : getElementVolume(noiseEl);
         if (noiseEl.paused)
-            noiseEl.volume = 0;
+            setElementVolume(noiseEl, 0);
         noiseEl.play().catch(() => { });
         const startTime = performance.now();
         const step = () => {
             const t = Math.min(1, (performance.now() - startTime) / durationMs);
             try {
-                noiseEl.volume = Math.max(0, Math.min(1, startVol + (targetVolume - startVol) * t));
+                setElementVolume(noiseEl, startVol + (targetVolume - startVol) * t);
             }
             catch (e) { }
             if (t < 1) {
@@ -85,11 +89,11 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
         const token = ++noiseFadeTokenRef.current;
         cancelNoiseFade();
         const startTime = performance.now();
-        const startVol = noiseEl.volume;
+        const startVol = getElementVolume(noiseEl);
         const step = () => {
             const t = Math.min(1, (performance.now() - startTime) / durationMs);
             try {
-                noiseEl.volume = Math.max(0, startVol * (1 - t));
+                setElementVolume(noiseEl, startVol * (1 - t));
             }
             catch (e) { }
             if (t < 1) {
@@ -123,7 +127,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
             }
             try {
                 if (!noiseEl.paused) {
-                    noiseEl.volume = 0;
+                    setElementVolume(noiseEl, 0);
                     noiseEl.pause();
                     onComplete?.();
                 }
@@ -157,7 +161,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
     // 개별 레이스를 전부 틀어막는 대신, 잘못된 상태를 주기적으로 감지해 회수한다.
     // 두 번 연속(약 0.8초) 확인 후에 정지 — 멀티소스 트랙 전환처럼 메인이 잠깐 멈추는
     // 정상 구간에서 소음이 출렁이지 않게 하기 위한 유예다.
-    const noiseVolume = noisePlayer ? effectiveNoiseVolume(noisePlayer.settings) : 0;
+    const noiseVolume = noisePlayer ? noiseElementVolume(noisePlayer.settings) : 0;
     const noiseInUse = !!noisePlayer?.settings.enabled && noiseVolume > 0;
     useEffect(() => {
         // 소음이 이번 재생 세션에서 아예 꺼져 있으면(noiseInUse=false) noiseEl은 절대
@@ -220,7 +224,7 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
         const noiseEl = noiseAudioRef.current;
         if (!noiseEl)
             return;
-        const volume = ns ? effectiveNoiseVolume(ns) : 0;
+        const volume = ns ? noiseElementVolume(ns) : 0;
         if (!ns || !ns.enabled || volume === 0) {
             fadeOutNoise();
             return;
@@ -267,12 +271,12 @@ export function useNoiseFade({ noisePlayer, audioRef, playbackStateRef, }) {
                 else {
                     // 이미 재생 중 — 볼륨만 부드럽게 조절
                     cancelNoiseFade();
-                    const startVol = noiseEl.volume;
+                    const startVol = getElementVolume(noiseEl);
                     const startTime = performance.now();
                     const ramp = () => {
                         const t = Math.min(1, (performance.now() - startTime) / 150);
                         try {
-                            noiseEl.volume = startVol + (volume - startVol) * t;
+                            setElementVolume(noiseEl, startVol + (volume - startVol) * t);
                         }
                         catch (e) { }
                         if (t < 1)

package/dist/packages/core/src/components/Training/useTTSPlayback.d.ts

@@ -8,7 +8,7 @@ type PlaybackState = 'stopped' | 'playing' | 'paused';
 export declare function useTTSPlayback({ ttsText, playbackRate, mainVolume, fillRef, waveProgressRef, setProgress, setPlaybackState, setStateLocal, fadeInNoise, fadeOutNoise, noiseSettingsRef, onDoneRef, handleEndRef, }: {
     ttsText?: string | string[] | null;
     playbackRate: number;
-    /** 음성 볼륨 0–1 — 부르는 쪽이 문제 소리 볼륨(effectiveSpeechVolume)을 넘긴다 */
+    /** 음성 볼륨 0–1 — 문제 소리 = 전체 소리(effectiveSpeechVolume) */
     mainVolume: number;
     fillRef: RefObject<HTMLDivElement | null>;
     waveProgressRef: RefObject<HTMLDivElement | null>;

package/dist/packages/core/src/types/training.d.ts

@@ -16,13 +16,13 @@ export type CoreNoiseSettings = {
     level: number;
     /**
      * 소음 비율 — 문제 소리 대비 소음의 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
-     * 문제 소리 = mainVolume × min(1, 1/noiseRatio), 소음 = mainVolume × min(1, noiseRatio).
+     * 문제 소리 = mainVolume, 소음 들리는 크기 = mainVolume × noiseRatio(원본 소음 파일 기준).
      * 없으면 `level` 에서 옮긴다.
      */
     noiseRatio?: number;
     /** 소음 재생 속도(playbackRate). 0.75–1.25, 기본 1. */
     speed: number;
-    /** 전체 소리 — 두 소리 중 큰 쪽의 크기. 0–1, 기본 1. 실제 두 볼륨은 `noiseRatio` 로 나뉜다. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
+    /** 전체 소리 = 문제 소리 볼륨. 0–1, 기본 1. 소음은 이 값 × `noiseRatio`. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
     mainVolume: number;
     /** 문장(메인) 재생 속도(playbackRate). 0.5–1.5, 기본 1. 계정 설정("훈련" 패널)과 훈련 화면 툴팁이 함께 영속화한다. */
     mainSpeed: number;

package/dist/packages/core/src/utils/audioMeter.d.ts

@@ -1,19 +1,41 @@
 /**
- * 오디오 레벨 미터용 Web Audio 유틸.
+ * 오디오 레벨 미터 + 볼륨용 Web Audio 유틸.
  *
- * HTMLMediaElement를 AnalyserNode에 연결해 실시간 레벨(RMS)을 읽을 수 있게 한다.
- * - createMediaElementSource는 엘리먼트당 1회만 가능 → WeakMap으로 캐싱.
- * - 분석을 위해 라우팅하면 destination 연결이 끊기면 무음이 되므로,
- *   source를 analyser와 destination 양쪽에 연결한다.
- * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous"가 설정되고
- *   서버가 CORS를 허용해야 분석이 가능하다(아니면 0으로 읽힘, 재생은 정상).
+ * HTMLMediaElement 를 한 그래프에 태운다: `source → GainNode → (AnalyserNode, destination)`.
+ * - createMediaElementSource 는 엘리먼트당 1회만 가능 → WeakMap 으로 캐싱.
+ * - **볼륨은 GainNode 로 건다**(0.126.0). 실제 iPhone·iPad 에서는 `HTMLMediaElement.volume` 을
+ *   스크립트로 바꿔도 소리에 안 먹는다(Apple 문서 — 늘 1). 그래프에 태운 요소는 volume 을 1 로
+ *   두고 `gain` 으로 크기를 정하므로 기기와 상관없이 먹는다. 미터(analyser)는 gain 뒤라 들리는
+ *   크기를 읽는다(요소 volume 이 소스 출력에 걸리던 전과 같은 결).
+ * - **달리는(running) AudioContext 에만 태운다.** 태운 순간부터 요소 소리는 destination 연결로만
+ *   나가므로, suspended(자동재생 정책) 컨텍스트에 태우면 resume 전까지 무음이다. 그래서 suspended
+ *   이면 resume 이 끝난 뒤에 태우고, 그 전에는 요소가 제 볼륨으로 직접 울린다.
+ * - Web Audio 가 없거나 태우기에 실패하면(미지원·이미 다른 그래프에 소스됨 등) 요소 volume 으로 물러선다.
+ * - cross-origin 소스는 엘리먼트에 crossOrigin="anonymous" 가 있고 서버가 CORS 를 허용해야 그래프
+ *   출력이 무음이 되지 않는다(코어의 문장·소음 요소는 둘 다 붙인다).
  */
 /** 미터 AudioContext를 사용자 제스처 이후 resume(자동재생 정책 대응). */
 export declare function resumeAudioMeter(): void;
 /**
- * 엘리먼트에 연결된 AnalyserNode를 반환(없으면 생성·캐싱).
- * 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
+ * 엘리먼트를 그래프에 태우고 AnalyserNode 를 준다(이미 태웠으면 그것).
+ * 컨텍스트가 suspended 면 resume 을 기다린 뒤 태운다 — resume 이 안 되면(제스처 없음) null 이고
+ * 요소는 제 볼륨으로 계속 울린다. Web Audio 미지원·실패도 null.
+ * @public
+ */
+export declare function routeElementAudio(el: HTMLMediaElement | null | undefined): Promise<AnalyserNode | null>;
+/**
+ * 엘리먼트에 연결된 AnalyserNode 를 반환(달리는 컨텍스트면 지금 태워서).
+ * 컨텍스트가 suspended 면 **지금은 null** 을 주고 resume 뒤 태우기를 걸어 둔다 — 나중 값이 필요하면
+ * `routeElementAudio` 를 기다린다. 실패 시 null(미지원/이미 다른 그래프에 소스됨 등).
  */
 export declare function getElementAnalyser(el: HTMLMediaElement | null | undefined): AnalyserNode | null;
+/**
+ * @public 요소 볼륨(0~1)을 건다. 그래프에 태운 요소면 요소 volume 은 1 로 두고 GainNode 에
+ * (짧은 시정수로 매끄럽게) 걸고 'gain', 아니면 요소 volume 에 걸고 'element'. 부르는 쪽이 매 프레임
+ * 불러 램프를 만들어도 된다.
+ */
+export declare function setElementVolume(el: HTMLMediaElement, volume: number): 'gain' | 'element';
+/** @public 요소에 걸려고 한 볼륨(0~1) — 램프 출발점. 건 적이 없으면 요소 volume. */
+export declare function getElementVolume(el: HTMLMediaElement): number;
 /** AnalyserNode의 현재 레벨(RMS, 0~1). */
 export declare function readLevel(analyser: AnalyserNode, buffer: Float32Array<ArrayBuffer>): number;