feat: add tests

docs/commands.md

@@ -114,15 +114,18 @@ Currently, synchronization only works between files of the same format:
 #### For LRC Files:
 
 - **When entry counts match**: The source timeline is directly applied to the target content.
-- **When entry counts differ**: The source timeline is scaled to match the target content using linear interpolation.
+- **When entry counts differ**: The source timeline is scaled to match the target content using linear interpolation:
+  - For each target entry position, a corresponding position in the source timeline is calculated
+  - Times are linearly interpolated between the nearest source entries
+  - This ensures smooth and proportional timing across entries of different counts
 - **Preserved from target**: All content text and metadata (artist, title, etc.).
 - **Modified in target**: Only timestamps are updated.
 
 #### For SRT Files:
 
 - **When entry counts match**: Both start and end times from the source are directly applied to the target entries.
-- **When entry counts differ**: A scaled approach is used:
-  - Start times are taken from proportionally matched source entries
+- **When entry counts differ**: A scaled approach using linear interpolation is used:
+  - Start times are calculated using linear interpolation between the nearest source entries
   - End times are calculated based on source entry durations
   - The timing relationship between entries is preserved
 - **Preserved from target**: All subtitle text content.
@@ -131,17 +134,35 @@ Currently, synchronization only works between files of the same format:
 #### For VTT Files:
 
 - **When entry counts match**: Both start and end times from the source are directly applied to the target entries.
-- **When entry counts differ**: A scaled approach is used, similar to SRT synchronization:
-  - Start times are taken from proportionally matched source entries
+- **When entry counts differ**: A scaled approach using linear interpolation is used, similar to SRT synchronization:
+  - Start times are calculated using linear interpolation between the nearest source entries
   - End times are calculated based on source entry durations
   - The timing relationship between entries is preserved
 - **Preserved from target**: All subtitle text content, formatting, cue settings, and styling.
 - **Modified in target**: Timestamps are updated and cue identifiers are standardized (sequential from 1).
 
+### Timeline Interpolation Details
+
+The sync command uses linear interpolation to handle different entry counts between source and target files:
+
+- **What is linear interpolation?** It's a mathematical technique for estimating values between two known points. For timeline synchronization, it creates a smooth transition between source timestamps when applied to a different number of target entries.
+
+- **How it works:**
+  1. The algorithm maps each target entry position to a corresponding position in the source timeline
+  2. For each target position, it calculates a timestamp by interpolating between the nearest source timestamps
+  3. The calculation ensures proportionally distributed timestamps that maintain the rhythm of the original
+
+- **Example:** If source file has entries at 1s, 5s, and 9s (3 entries), and target has 5 entries, the interpolated timestamps would be approximately 1s, 3s, 5s, 7s, and 9s, maintaining even spacing.
+
+- **Benefits of linear interpolation:**
+  - More accurate timing when entry counts differ significantly
+  - Preserves the pacing and rhythm of the source timeline
+  - Handles both expanding (target has more entries) and contracting (target has fewer entries) scenarios
+
 ### Edge Cases
 
 - If the source file has no timing information, the target remains unchanged.
-- If source duration calculations result in negative values, a default 3-second duration is applied.
+- If source duration calculations result in negative values, a default duration of zero is applied (improved from previous 3-second default).
 - The command displays a warning when entry counts differ but proceeds with the scaled synchronization.
 - Format-specific features from the target file (such as styling, alignment, metadata) are preserved. The sync operation only replaces timestamps, not any other formatting or content features.
 

docs/zh-Hans/commands.md

@@ -114,15 +114,18 @@ sub-cli sync <源文件> <目标文件>
 #### 对于LRC文件：
 
 - **当条目数匹配时**: 源时间线直接应用于目标内容。
-- **当条目数不同时**: 源时间线使用线性插值进行缩放以匹配目标内容。
+- **当条目数不同时**: 源时间线使用线性插值进行缩放以匹配目标内容：
+  - 对于每个目标条目位置，计算源时间线中的对应位置
+  - 在最近的源条目之间进行线性插值计算时间
+  - 这确保了在不同数量的条目间实现平滑和比例化的时间分布
 - **从目标保留**: 所有内容文本和元数据（艺术家、标题等）。
 - **在目标中修改**: 只更新时间戳。
 
 #### 对于SRT文件：
 
 - **当条目数匹配时**: 源的开始和结束时间直接应用于目标条目。
-- **当条目数不同时**: 使用缩放方法：
-  - 开始时间取自按比例匹配的源条目
+- **当条目数不同时**: 使用基于线性插值的缩放方法：
+  - 开始时间使用源条目之间的线性插值计算
   - 结束时间根据源条目时长计算
   - 保持条目之间的时间关系
 - **从目标保留**: 所有字幕文本内容。
@@ -131,17 +134,35 @@ sub-cli sync <源文件> <目标文件>
 #### 对于VTT文件：
 
 - **当条目数匹配时**: 源的开始和结束时间直接应用于目标条目。
-- **当条目数不同时**: 使用缩放方法：
-  - 开始时间取自按比例匹配的源条目
+- **当条目数不同时**: 使用基于线性插值的缩放方法，类似于SRT同步：
+  - 开始时间使用源条目之间的线性插值计算
   - 结束时间根据源条目时长计算
   - 保持条目之间的时间关系
 - **从目标保留**: 所有字幕文本内容和样式信息。
 - **在目标中修改**: 更新时间戳并标准化提示标识符。
 
+### 时间线插值详情
+
+同步命令使用线性插值来处理源文件和目标文件之间不同的条目数量：
+
+- **什么是线性插值？** 这是一种估计两个已知点之间值的数学技术。对于时间线同步，它在应用于不同数量的目标条目时，可以在源时间戳之间创建平滑过渡。
+
+- **工作原理：**
+  1. 算法将每个目标条目位置映射到源时间线中的对应位置
+  2. 对于每个目标位置，通过插值计算最近的源时间戳之间的时间戳
+  3. 计算确保按比例分布的时间戳，保持原始节奏
+
+- **示例：** 如果源文件在1秒、5秒和9秒有条目（共3个条目），而目标有5个条目，插值后的时间戳将大约为1秒、3秒、5秒、7秒和9秒，保持均匀间隔。
+
+- **线性插值的好处：**
+  - 当条目数相差很大时，提供更准确的时间
+  - 保持源时间线的节奏和韵律
+  - 既能处理扩展（目标条目更多）也能处理收缩（目标条目更少）的情况
+
 ### 边缘情况
 
 - 如果源文件没有时间信息，目标保持不变。
-- 如果源时长计算导致负值，会应用默认的3秒时长。
+- 如果源时长计算导致负值，会应用默认的零秒时长（改进自之前的3秒默认值）。
 - 当条目数不同时，命令会显示警告但会继续进行缩放同步。
 - 目标文件中的特定格式功能（如样式、对齐方式、元数据）会被保留。同步操作只替换时间戳，不会更改任何其他格式或内容功能。