From f8b82bcd999dd007874db2db5ca7c4f6a4de9470 Mon Sep 17 00:00:00 2001 From: Antoine Jaury Date: Mon, 6 Jul 2026 17:01:01 +0200 Subject: [PATCH] new: add documentation for subtitle format, phonetics, and translation structure --- README.md | 66 ++++++++++++++++++++++++++++++----------------- docs/SUBTITLES.md | 37 ++++++++++++++++++++++++++ 2 files changed, 79 insertions(+), 24 deletions(-) create mode 100644 docs/SUBTITLES.md diff --git a/README.md b/README.md index d181933..0f796d6 100644 --- a/README.md +++ b/README.md @@ -1,28 +1,34 @@ This is a Kotlin Multiplatform project targeting Android, iOS, Web, Desktop (JVM). -* [/iosApp](./iosApp/iosApp) contains an iOS application. Even if you’re sharing your UI with Compose Multiplatform, - you need this entry point for your iOS app. This is also where you should add SwiftUI code for your project. +* [/iosApp](./iosApp/iosApp) contains an iOS application. Even if you’re sharing your UI with + Compose Multiplatform, + you need this entry point for your iOS app. This is also where you should add SwiftUI code for + your project. -* [/shared](./shared/src) is for code that will be shared across your Compose Multiplatform applications. +* [/shared](./shared/src) is for code that will be shared across your Compose Multiplatform + applications. It contains several subfolders: - - [commonMain](./shared/src/commonMain/kotlin) is for code that’s common for all targets. - - Other folders are for Kotlin code that will be compiled for only the platform indicated in the folder name. - For example, if you want to use Apple’s CoreCrypto for the iOS part of your Kotlin app, - the [iosMain](./shared/src/iosMain/kotlin) folder would be the right place for such calls. - Similarly, if you want to edit the Desktop (JVM) specific part, the [jvmMain](./shared/src/jvmMain/kotlin) - folder is the appropriate location. + - [commonMain](./shared/src/commonMain/kotlin) is for code that’s common for all targets. + - Other folders are for Kotlin code that will be compiled for only the platform indicated in the + folder name. + For example, if you want to use Apple’s CoreCrypto for the iOS part of your Kotlin app, + the [iosMain](./shared/src/iosMain/kotlin) folder would be the right place for such calls. + Similarly, if you want to edit the Desktop (JVM) specific part, + the [jvmMain](./shared/src/jvmMain/kotlin) + folder is the appropriate location. ### Running the apps -Use the run configurations provided by the run widget in your IDE's toolbar. You can also use these commands and options: +Use the run configurations provided by the run widget in your IDE's toolbar. You can also use these +commands and options: - Android app: `./gradlew :androidApp:assembleDebug` - Desktop app: - - Hot reload: `./gradlew :desktopApp:hotRun --auto` - - Standard run: `./gradlew :desktopApp:run` + - Hot reload: `./gradlew :desktopApp:hotRun --auto` + - Standard run: `./gradlew :desktopApp:run` - Web app: - - Wasm target (faster, modern browsers): `./gradlew :webApp:wasmJsBrowserDevelopmentRun` - - JS target (slower, supports older browsers): `./gradlew :webApp:jsBrowserDevelopmentRun` + - Wasm target (faster, modern browsers): `./gradlew :webApp:wasmJsBrowserDevelopmentRun` + - JS target (slower, supports older browsers): `./gradlew :webApp:jsBrowserDevelopmentRun` - iOS app: open the [/iosApp](./iosApp) directory in Xcode and run it from there. ### Running tests @@ -32,30 +38,42 @@ Use the run button in your IDE's editor gutter, or run tests using Gradle tasks: - Android tests: `./gradlew :shared:testAndroidHostTest` - Desktop tests: `./gradlew :shared:jvmTest` - Web tests: - - Wasm target: `./gradlew :shared:wasmJsTest` - - JS target: `./gradlew :shared:jsTest` + - Wasm target: `./gradlew :shared:wasmJsTest` + - JS target: `./gradlew :shared:jsTest` - iOS tests: `./gradlew :shared:iosSimulatorArm64Test` --- -Learn more about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html), +Learn more +about [Kotlin Multiplatform](https://www.jetbrains.com/help/kotlin-multiplatform-dev/get-started.html), [Compose Multiplatform](https://github.com/JetBrains/compose-multiplatform/#compose-multiplatform), [Kotlin/Wasm](https://kotl.in/wasm/)… -We would appreciate your feedback on Compose/Web and Kotlin/Wasm in the public Slack channel [#compose-web](https://slack-chats.kotlinlang.org/c/compose-web). -If you face any issues, please report them on [YouTrack](https://youtrack.jetbrains.com/newIssue?project=CMP). +We would appreciate your feedback on Compose/Web and Kotlin/Wasm in the public Slack +channel [#compose-web](https://slack-chats.kotlinlang.org/c/compose-web). +If you face any issues, please report them +on [YouTrack](https://youtrack.jetbrains.com/newIssue?project=CMP). ## Dependency injection -For dependency injection, we use [Koin](https://insert-koin.io/). To know more about the integration with Compose, -please refer to the [Koin Compose documentation](https://insert-koin.io/docs/reference/koin-compose/compose). +For dependency injection, we use [Koin](https://insert-koin.io/). To know more about the integration +with Compose, +please refer to +the [Koin Compose documentation](https://insert-koin.io/docs/reference/koin-compose/compose). ## Navigation -For navigation, Navigation3 is used: https://kotlinlang.org/docs/multiplatform/compose-navigation-3.html +For navigation, Navigation3 is +used: https://kotlinlang.org/docs/multiplatform/compose-navigation-3.html -For implementation details, please refer to the [Navigation3 Android documentation](https://developer.android.com/guide/navigation/navigation-3/basics). +For implementation details, please refer to +the [Navigation3 Android documentation](https://developer.android.com/guide/navigation/navigation-3/basics). ## Audio -OGG Vorbis is not correctly supported on iOS. Prefer M4A+AAC instead. For instance, audio duration is shorter on iOS with OGG. Therefore, subtitles are not correctly synchronized. \ No newline at end of file +OGG Vorbis is not correctly supported on iOS. Prefer M4A+AAC instead. For instance, audio duration +is shorter on iOS with OGG. Therefore, subtitles are not correctly synchronized. + +## Subtitles + +To know more about subtitles, see: [SUBTITLES.md](docs/SUBTITLES.md) \ No newline at end of file diff --git a/docs/SUBTITLES.md b/docs/SUBTITLES.md new file mode 100644 index 0000000..1fdaa27 --- /dev/null +++ b/docs/SUBTITLES.md @@ -0,0 +1,37 @@ +# Subtitles + +## Format + +The LRC lyrics format is used for subtitles with no end time. + +## Tools + +We recommend using Subtitle Edit open source software for editing subtitles. + +Source code: https://github.com/SubtitleEdit/subtitleedit + +## Phonetics + +To highlight muted characters, use curly brackets `{}` around the character that is muted +phonetically. + +To highlight linking characters, use square brackets `[]` around the character that is linked +phonetically. Don't add space before or after the square brackets. + +## File naming & translation + +The main file is the transcription file and follow the file name pattern: +`_st_bzh.lrc`. + +The translation file should follow the file name pattern: `_st_fr.lrc` and have the +same timestamps as the matching transcription. + +The `` part of the name should also be the same as the one in the transcription file. + +## Package structure + +The transcription and translation files should be in the same directory, under the `:data:ressources` +module, in `comminMain/composeResources/files`. They are exposed as Compose resources. + +For more, see: https://kotlinlang.org/docs/multiplatform/compose-multiplatform-resources.html +