@ihabdevteam/core 0.121.0 → 0.123.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.121.0";
+export declare const CORE_VERSION = "0.123.0";
 
 /** @public */
 declare const coreDefault: Record<string, unknown>;
@@ -1362,13 +1362,14 @@ export declare type CoreNoiseSettings = {
      */
     level: number;
     /**
-     * 소음 비율 — 문제 소리(`mainVolume`) 대비 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
-     * 실제 소음 볼륨 = min(1, mainVolume × noiseRatio). 없으면 `level` 에서 옮긴다.
+     * 소음 비율 — 문제 소리 대비 소음의 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
+     * 문제 소리 = mainVolume × min(1, 1/noiseRatio), 소음 = mainVolume × min(1, 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/components/Training/AudioPlayerWaveForm.js

@@ -118,7 +118,7 @@ export default function WaveForm(props) {
         return () => { cancelled = true; };
     }, [noiseSrc, barsTotal, totalDuration, noiseSpeed]);
     /* eslint-enable react-hooks/set-state-in-effect */
-    // 문장: 자기 최고치로 정규화해 세로 영역을 다 씀 × 재생 소리(볼륨).
+    // 문장: 자기 최고치로 정규화해 세로 영역을 다 씀 × 문제 소리 볼륨(부모가 effectiveSpeechVolume 을 mainVolume 으로 넘김).
     // 소음은 이 문장 최고치(sentenceMaxPeak)를 공통 분모로 써서 서로 비율이 유지된다.
     const mainAmp = Math.max(0, Math.min(1, mainVolume));
     const sentenceMaxPeak = useMemo(() => (wavePeaks && wavePeaks.length) ? (Math.max(...wavePeaks) || 1) : 1, [wavePeaks]);

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

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

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

@@ -11,9 +11,15 @@ 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` 0~2배)로
-   정한다. 실제 소음 볼륨 = min(1, mainVolume × noiseRatio) — 전체 소리를 줄이면 소음도 따라
-   준다. 예전에는 소음 크기(level/9)가 전체 소리와 따로 움직였다. */
+   전체 소리(`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)가 전체 소리와 따로 움직였다. */
 /** @public 소음 비율 상한(배). */
 export const NOISE_RATIO_MAX = 2;
 /** @public 소음 비율 칸(배). */
@@ -35,10 +41,29 @@ export function noiseRatioOf(settings) {
         return 1;
     return 한칸반올림(비율자르기(소음 / 전체));
 }
-/** @public 실제 소음 볼륨(0~1) = min(1, mainVolume × noiseRatioOf(settings)). 켜짐 여부는 보지 않는다. */
-export function effectiveNoiseVolume(settings) {
+/**
+ * 전체 소리와 비율을 확정한다. `noiseRatio` 가 없는 옛 기록은 옛 뜻(문제 소리 = mainVolume,
+ * 소음 = level/9)이 **들리던 크기 그대로** 남도록 옮긴다 — R = noiseRatioOf, 그리고 R > 1 이면
+ * 소음이 큰 쪽이므로 전체 소리 = level/9.
+ */
+function 확정(settings) {
     const 전체 = Math.min(1, Math.max(0, Number(settings.mainVolume) || 0));
-    return Math.min(1, 전체 * noiseRatioOf(settings));
+    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);
+}
+/** @public 실제 문제 소리 볼륨(0~1) = mainVolume × min(1, 1/비율). 비율 0 이면 mainVolume. */
+export function effectiveSpeechVolume(settings) {
+    const { mainVolume, noiseRatio } = 확정(settings);
+    return noiseRatio > 1 ? mainVolume / noiseRatio : mainVolume;
 }
 /**
  * @public 설정에 조각을 덮는다 — `{ ...base, ...patch }` 에 비율 규칙 하나를 더한 것.
@@ -47,12 +72,16 @@ export function effectiveNoiseVolume(settings) {
  * 옛 `noiseOverride`). 그대로 덮으면 base 의 `noiseRatio`(기본값 1 등)가 남아 level 을 가려
  * 버리므로, 덮은 결과의 level·mainVolume 으로 비율을 셈해 **그 자리에서 박아 둔다** —
  * 박지 않고 비워 두면 뒤에 전체 소리만 바꿀 때 비율이 따라 변해 소음이 옛날처럼 제자리에 선다.
+ * 비율이 1 을 넘으면 소음이 큰 쪽이므로 `mainVolume` 도 level/9 로 함께 박는다(옛날에 들리던
+ * 두 크기 그대로 — 예: level 9·mainVolume 0.5 → 비율 2·mainVolume 1 = 소음 1·문제 0.5).
  * `{ ...DEFAULT_NOISE_SETTINGS, ...saved }` 대신 이것을 쓴다.
  */
 export function mergeNoiseSettings(base, patch) {
     const merged = { ...base, ...(patch ?? {}) };
     if (patch && 'level' in patch && !(typeof patch.noiseRatio === 'number')) {
-        merged.noiseRatio = noiseRatioOf({ level: merged.level, mainVolume: merged.mainVolume });
+        const 박을것 = 확정({ level: merged.level, mainVolume: merged.mainVolume });
+        merged.noiseRatio = 박을것.noiseRatio;
+        merged.mainVolume = 박을것.mainVolume;
     }
     return merged;
 }

package/dist/packages/core/src/components/Training/NoiseSettingsTooltip.css

@@ -5,11 +5,11 @@
    border-radius(--radius-m, 20px)보다 작아서, Panel의 각진 배경이 Tooltip의 둥근 모서리 안쪽에 그대로
    보여 모서리가 제대로 표현되지 않았다 — Panel이 tooltip-content 전체를 꽉 채우므로 반지름을 맞춘다. */
 .noise-settings {
-  /* 위만 16px — 머리(.tooltip-content__header)의 구분선이 이미 위를 가르므로 20px 이면 첫 줄만
-     떠 보였다(말귀 사용자 "여백이 넓어보이네?"). 1280px 에서 잰 눈에 보이는 틈:
-     구분선→첫 줄 36px, 줄→줄 33·32px. 16px 에서 32·33·32 로 줄 사이 리듬과 같아진다
-     (8px 이면 24px 로 오히려 줄 사이보다 좁다). 좌우·아래는 그대로. */
-  padding: 16px 20px 20px;
+  /* 위는 0 — 머리(.tooltip-content__header)의 구분선이 이미 위를 가르고, 첫 줄(.panel-row)이
+     제 높이 가운데에 내용을 세우므로 패널 위 안쪽 여백이 겹치면 첫 줄만 떠 보인다.
+     20px(말귀 사용자 "여백이 넓어보이네?") → 16px(0.119.0, 줄 사이 리듬에 맞춤) 뒤에도 떠 보인다는
+     말귀 사용자 판단으로 0(0.122.0). 좌우·아래는 그대로. */
+  padding: 0 20px 20px;
   box-sizing: border-box;
   max-width: calc(100vw - 40px);
   border-radius: var(--radius-m);

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

@@ -7,7 +7,7 @@ import { useTranslation } from "react-i18next";
 import { downloadSound, getSignedOrPublicUrl, resolveSoundPath } from '../../utils/storage';
 import { getTTSUrlResolver } from '../../utils/ttsConfig';
 import { getElementAnalyser, resumeAudioMeter } from '../../utils/audioMeter';
-import { useNoisePlayer, effectiveNoiseVolume } from './NoisePlayerContext';
+import { useNoisePlayer, effectiveNoiseVolume, effectiveSpeechVolume } from './NoisePlayerContext';
 import { useNoiseFade } from './useNoiseFade';
 import { useTTSPlayback } from './useTTSPlayback';
 import './TrainingStepAudioPlayer.css';
@@ -97,8 +97,10 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     // 문장(메인) 재생 속도·볼륨 — 하단 소음설정 툴팁과 공유(NoisePlayerContext)
     const playbackRate = noisePlayer?.playbackRate ?? 1.0;
     const mainVolume = noisePlayer?.mainVolume ?? 1.0;
-    // 실제 소음 볼륨 — 전체 소리 × 소음 비율(상한 1). 파형의 소음 막대도 이 값으로 그린다.
+    // 실제 두 볼륨 — 전체 소리(큰 쪽 크기)를 소음 비율로 나눈다. 파형 막대도 이 값으로 그린다.
     const noiseVolume = noisePlayer ? effectiveNoiseVolume(noisePlayer.settings) : 0;
+    // 소음을 끈 판(소음 종류 "없음")은 들리지 않는 소음에 문제 소리를 양보하지 않는다 — 전체 소리 그대로.
+    const speechVolume = noisePlayer?.settings.enabled ? effectiveSpeechVolume(noisePlayer.settings) : mainVolume;
     const [fillCompletionPhase, setFillCompletionPhase] = useState('idle');
     const [noticeMessage, setNoticeMessage] = useState("");
     const [noticePosition] = useState("top");
@@ -141,7 +143,8 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
     const { startTTS, stopTTS } = useTTSPlayback({
         ttsText,
         playbackRate,
-        mainVolume,
+        // TTS 음성 = 문제 소리 — 전체 소리가 아니라 비율로 나뉜 문제 소리 볼륨
+        mainVolume: speechVolume,
         fillRef,
         waveProgressRef,
         setProgress,
@@ -947,15 +950,51 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
         }
         catch (e) { }
     }, [playbackRate]);
-    // 문장(메인) 볼륨 반영
+    // 문장(메인) 볼륨 반영 — 문제 소리 볼륨(effectiveSpeechVolume). 전체 소리·소음 비율 어느 쪽을
+    // 바꿔도 달라진다. 재생 중이면 소음과 같은 150ms 램프로 옮기고, 멈춰 있으면 바로 건다.
+    // 백그라운드 탭에서는 RAF 가 멈춰 램프가 중간에 설 수 있으므로 끝값을 타이머로 한 번 더 박는다.
+    const speechRampRef = useRef({ raf: null, timer: null });
     useEffect(() => {
-        try {
-            const a = audioRef.current;
-            if (a)
-                a.volume = Math.max(0, Math.min(1, mainVolume));
+        const a = audioRef.current;
+        if (!a)
+            return;
+        const target = Math.max(0, Math.min(1, speechVolume));
+        const ramp = speechRampRef.current;
+        const 끊기 = () => {
+            if (ramp.raf !== null) {
+                cancelAnimationFrame(ramp.raf);
+                ramp.raf = null;
+            }
+            if (ramp.timer !== null) {
+                clearTimeout(ramp.timer);
+                ramp.timer = null;
+            }
+        };
+        끊기();
+        const from = a.volume;
+        if (a.paused || Math.abs(from - target) < 0.001 || typeof requestAnimationFrame !== 'function') {
+            try {
+                a.volume = target;
+            }
+            catch (e) { }
+            return;
         }
-        catch (e) { }
-    }, [mainVolume]);
+        const start = performance.now();
+        const step = () => {
+            const t = Math.min(1, (performance.now() - start) / 150);
+            try {
+                a.volume = from + (target - from) * t;
+            }
+            catch (e) { }
+            ramp.raf = t < 1 ? requestAnimationFrame(step) : null;
+        };
+        ramp.raf = requestAnimationFrame(step);
+        ramp.timer = setTimeout(() => { 끊기(); try {
+            a.volume = target;
+        }
+        catch (e) { } }, 200);
+        return 끊기;
+    }, [speechVolume]);
     // fill (진행 마커) 클래스 및 초기 위치 계산 — RAF 루프에서 .style.left를 직접 갱신합니다.
     const isFillHolding = fillCompletionPhase === 'hold';
     const isFillOutAnimating = fillCompletionPhase === 'out';
@@ -969,5 +1008,5 @@ export default function TrainingStepAudioPlayer({ btnLabel, soundSrc, bucketPath
                         onFocus: showListenTip, onBlur: hideListenTip, children: _jsx("span", { ref: listenBtnRef, className: "audio-player__button-triangle-wrap", children: _jsx("svg", { className: "audio-player__button-triangle", viewBox: "0 0 24 24", "aria-hidden": "true", children: _jsx("path", { ref: triPathRef, d: "M13.2 7.7 L16.5 9.85 Q20.2 12 16.5 14.15 L10 18.3 Q7 19.7 7 16.3 L7 7.7 Q7 4.3 10 5.7 L13.2 7.7" }) }) }) })) : null, listenBtnRect && (_jsx(InfoTooltip, { anchorRect: listenBtnRect, text: typeof label === 'string' && label ? label : t('training.listenLabel', '문장 듣기'), offset: 8 })), _jsxs("div", { className: `audio-player__play ${stateLocal === "playMode" || displayedPlaying ? "is-visible" : ""}`, children: [_jsxs("div", { ref: btnsRef, className: "audio-player__buttons", children: [_jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-back", onClick: handlePrev, ariaLabel: t('training.prev', '이전'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: displayedPlaying ? "pause" : "play", onClick: handleToggle, ariaLabel: t('common.playPause', '재생 / 멈춤'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' }), _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "square", onClick: handleStop, ariaLabel: t('training.stop', '정지'), width: "60px", variant: "transparent-white", "aria-hidden": "true", tabIndex: -1, disabled: stateLocal !== 'playMode' }), sourceButtonCount > 1 ? (_jsx("div", { ref: sourceButtonsRef, className: "audio-player__source-buttons", children: Array.from({ length: sourceButtonCount }).map((_, idx) => (_jsx(Button, { size: 32, type: "dot", shape: "pill", useBorder: false, label: String(idx + 1), onClick: () => { try {
                                                 handleJumpTo(idx);
                                             }
-                                            catch (e) { } }, ariaLabel: t('training.sourcePlay', { n: idx + 1 }), variant: "transparent-white", selected: 구간표시 && currentIndex === idx, disabled: stateLocal !== 'playMode' || !(Array.isArray(sources) && sources[idx]), showTooltipInfo: true }, idx))) })) : null, (!Array.isArray(sources) || sources.length <= 1) ? (_jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "repeat", onClick: handleReplay, ariaLabel: t('common.replay', '다시듣기'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })) : null, _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-forward", onClick: handleNext, ariaLabel: t('training.next', '다음'), width: "60px", variant: "transparent-white", "aria-hidden": true, tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "check", onClick: handleEnd, ariaLabel: t('common.done', '완료'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })] }), _jsxs("div", { className: "audio-player__slider", children: [_jsx("div", { className: fillClass, ref: fillRef, style: { left: `${fillLeftPercent}%` }, "aria-hidden": "true" }), (showSoundWaveForm || showNoiseWaveForm) && (_jsx(WaveForm, { segments: currentSegments, progress: progress, totalDuration: totalDuration, onSegmentClick: handleJumpTo, waveProgressRef: waveProgressRef, showSoundWaveForm: showSoundWaveForm, noiseSrc: (showNoiseWaveForm && noisePlayer?.settings.enabled && noiseVolume > 0) ? activeNoiseUrl : null, noiseVolume: noiseVolume, noiseSpeed: noisePlayer?.settings.speed ?? 1, mainVolume: mainVolume, onReadyChange: handleWaveReadyChange }))] })] }), _jsx("audio", { ref: audioRef, crossOrigin: "anonymous", preload: "auto" })] }), !showSoundWaveForm && (_jsxs("p", { className: "audio-player__no-waveform caption-1", children: [_jsx(Icon, { icon: "triangle-alert", size: 14 }), t('training.noSoundWaveform', '소리 비교 문제는 웨이브폼을 표현하지 않습니다.')] })), _jsx(Toast, { message: noticeMessage, position: noticePosition, onClose: handleClearNotice })] }));
+                                            catch (e) { } }, ariaLabel: t('training.sourcePlay', { n: idx + 1 }), variant: "transparent-white", selected: 구간표시 && currentIndex === idx, disabled: stateLocal !== 'playMode' || !(Array.isArray(sources) && sources[idx]), showTooltipInfo: true }, idx))) })) : null, (!Array.isArray(sources) || sources.length <= 1) ? (_jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "repeat", onClick: handleReplay, ariaLabel: t('common.replay', '다시듣기'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })) : null, _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "skip-forward", onClick: handleNext, ariaLabel: t('training.next', '다음'), width: "60px", variant: "transparent-white", "aria-hidden": true, tabIndex: -1, disabled: stateLocal !== 'playMode' }), _jsx(Button, { size: 32, showTooltipInfo: true, type: "dot", shape: "pill", useBorder: false, icon: "check", onClick: handleEnd, ariaLabel: t('common.done', '완료'), width: "60px", variant: "transparent-white", disabled: stateLocal !== 'playMode' })] }), _jsxs("div", { className: "audio-player__slider", children: [_jsx("div", { className: fillClass, ref: fillRef, style: { left: `${fillLeftPercent}%` }, "aria-hidden": "true" }), (showSoundWaveForm || showNoiseWaveForm) && (_jsx(WaveForm, { segments: currentSegments, progress: progress, totalDuration: totalDuration, onSegmentClick: handleJumpTo, waveProgressRef: waveProgressRef, showSoundWaveForm: showSoundWaveForm, noiseSrc: (showNoiseWaveForm && noisePlayer?.settings.enabled && noiseVolume > 0) ? activeNoiseUrl : null, noiseVolume: noiseVolume, noiseSpeed: noisePlayer?.settings.speed ?? 1, mainVolume: speechVolume, onReadyChange: handleWaveReadyChange }))] })] }), _jsx("audio", { ref: audioRef, crossOrigin: "anonymous", preload: "auto" })] }), !showSoundWaveForm && (_jsxs("p", { className: "audio-player__no-waveform caption-1", children: [_jsx(Icon, { icon: "triangle-alert", size: 14 }), t('training.noSoundWaveform', '소리 비교 문제는 웨이브폼을 표현하지 않습니다.')] })), _jsx(Toast, { message: noticeMessage, position: noticePosition, onClose: handleClearNotice })] }));
 }

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

@@ -8,6 +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)을 넘긴다 */
     mainVolume: number;
     fillRef: RefObject<HTMLDivElement | null>;
     waveProgressRef: RefObject<HTMLDivElement | null>;

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

@@ -15,13 +15,14 @@ export type CoreNoiseSettings = {
      */
     level: number;
     /**
-     * 소음 비율 — 문제 소리(`mainVolume`) 대비 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
-     * 실제 소음 볼륨 = min(1, mainVolume × noiseRatio). 없으면 `level` 에서 옮긴다.
+     * 소음 비율 — 문제 소리 대비 소음의 배수, 0–2.0(0.1 칸). 1 = 소음과 문제 소리가 같은 크기.
+     * 문제 소리 = mainVolume × min(1, 1/noiseRatio), 소음 = mainVolume × min(1, 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/version.d.ts

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export declare const CORE_VERSION = "0.121.0";
+export declare const CORE_VERSION = "0.123.0";

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

@@ -46,4 +46,4 @@
  *
  * 값은 손으로 적고 `test/coreVersion.test.ts` 가 package.json 과 어긋나면 운다.
  */
-export const CORE_VERSION = '0.121.0';
+export const CORE_VERSION = '0.123.0';