This script can convert the sleep data from your Apple Watch to the format of the Dreem headband. This enables software like OSCAR to import it.
As of OSCAR 2.0.1, OSCAR does not provide a direct Apple Health or Apple Watch sleep-stage importer. Apple2Dreem fills that gap by converting exported Apple Health sleep stages into Dreem-compatible CSV files. Import the generated files in OSCAR using File > Import Dreem Data.
OSCAR's own Dreem loader explicitly identifies Apple2Dreem exports as genuine semicolon-delimited CSV files. See the OSCAR Dreem loader source.
One should provide input files from the Apple Watch using one of two iOS apps:
https://apps.apple.com/nl/app/health-auto-export-json-csv/id1115567069
To use this data format, specify the --type json option to Apple2Dreem.py (default).
App Settings:
- Select only Sleep Metrics (Sleep Analysis) for export,
- Export Format: JSON,
- Aggregate Data: False
https://apps.apple.com/us/app/simple-health-export-csv/id1535380115
The app exports CSV files compressed into a zip file. Apple2Dreem.py processes the exported zip files directly. To use this data format, specify the --type csv option to Apple2Dreem.py.
Note: The ZIP files can be targeted with -l "*.zip" when using -y csv.
The Apple2Dreem.py script converts sleep data exported from Apple Health (Apple Watch) into a format compatible with Dreem. It processes JSON files from Health Auto Export and CSV files inside ZIP archives from Simple Health Export CSV, and generates CSV files with sleep segments and statistics.
-
Parses Apple Health sleep data exported in JSON format and CSV format (ZIP).
-
Groups sleep data by night, considering sleep sessions from 19:00 to 11:00 the next day.
-
Handles time zones and time shifts, ensuring accurate time representation.
-
Generates CSV files containing detailed sleep analysis compatible with Dreem.
-
Automatically renames processed files to prevent reprocessing (optionally disableable).
-
Detects multiple data sources in an input file. If multiple sources are found and no source is specified, the file is skipped and the sources are listed.
-
-u/--use-sourceoption to process only a specified source when multiple sources exist. -
End-of-run summary now reports processed, skipped, and failed file counts.
- Python 3.9 or higher
- Required Python libraries:
- python-dateutil
- Clone or download the script to your local machine.
- Install the required libraries using pip:
python -m pip install --requirement requirements.txt
Run the conversion tests with:
python -m unittest discover --start-directory tests --verbose
The script can be run from the command line with various options. Below is the syntax and explanation of each option.
python Apple2Dreem.py [options]
-i, --input
Description: Specify the input folder containing the JSON files.
Default: Current directory (.)
Usage:
python Apple2Dreem.py -i path/to/input_folder
-o, --output
Description: Specify the output folder where CSV files will be saved.
Default: Same as input folder
Usage:
python Apple2Dreem.py -o path/to/output_folder
-f, --from
Description: Specify the start date and time for processing data.
Format: yyyy-MM-dd or yyyy-MM-dd-HH:mm
Default: Yesterday at 19:00
Usage:
python Apple2Dreem.py -f 2024-11-22
python Apple2Dreem.py -f 2024-11-22-19:00
-t, --to
Description: Specify the end date and time for processing data.
Format: yyyy-MM-dd or yyyy-MM-dd-HH:mm
Default: Today at 11:00
Usage:
python Apple2Dreem.py -t 2024-11-23
python Apple2Dreem.py -t 2024-11-23-11:00
-l, --filter
Description: Specify the input file filter (supports wildcards).
Default: HealthAutoExport-*.json
Usage:
python Apple2Dreem.py -l "MyHealthData-*.json"
-s, --shift
Description: Specify a time shift in seconds to adjust the timestamps in the data.
Default: 0 seconds
Usage:
python Apple2Dreem.py -s 3600 # Shift time by 1 hour forward
python Apple2Dreem.py -s -1800 # Shift time by 30 minutes backward
-y, --type
Description: Specify input file type: **json** (Health Auto Export app) or **csv** (Simple Health Export CSV app)
Default: json
Usage:
python Apple2Dreem.py -y csv
-r, --rename
Description: Specify whether to rename the input file upon completion ('true' or 'false')
Default: true
Usage:
python Apple2Dreem.py -r false
-u, --use-source
Description: When multiple data sources are present in the input, process only entries from the specified source. Suppresses the multi-source warning and skip.
Usage:
python Apple2Dreem.py -u "John's Apple Watch"
-h, --help
Description: Display the help message and exit.
Usage:
python Apple2Dreem.py -h
Process all default JSON files in the current directory with default dates and no time shift:
python Apple2Dreem.py
Process files in a specific input folder and output to a different folder:
python Apple2Dreem.py -i ./input_folder -o ./output_folder
Process data from a specific date range with a time shift of 1 hour forward:
python Apple2Dreem.py -f 2024-11-22 -t 2024-11-23 -s 3600
Use a custom file filter to process specific files:
python Apple2Dreem.py -l "MySleepData-2024-*.json"
If no options are specified, the script uses the following default values:
- Input folder: Current directory (.)
- Output folder: Same as input folder
- File filter: HealthAutoExport-*.json
- From date: Yesterday at 19:00 (7:00 PM)
- To date: Today at 11:00 (11:00 AM)
- Time shift: 0 seconds (no shift)
- Type: json
- Rename: true
The script searches for JSON or CSV.ZIP files in the input folder that match the specified file filter.
-
Reads each JSON file.
-
Parses sleep data entries, converting date strings into datetime objects.
-
Ensures all datetime objects are timezone-aware.
-
For JSON: reads Health Auto Export files and parses sleep entries.
-
For CSV: reads Simple Health Export CSV ZIP files (*.zip), parses rows, and maps stage values to JSON-equivalent stages.
- Groups sleep data entries by night, considering sessions from 19:00 to 11:00 the next day.
- Applies the specified date range (from_date and to_date).
- Creates 30-second segments between the start and end times.
- Maps sleep stages from the data to standard stages (Light, Deep, REM, etc.).
- Updates segments with sleep stage information.
- Calculates total sleep duration, sleep onset duration, durations of different sleep stages, wake after sleep onset, and number of awakenings.
- Generates a hypnogram representing sleep stages over time.
Writes the processed data to a CSV file in the output folder. The CSV file contains headers and a row with the calculated sleep statistics.
Renames the processed JSON files by prefixing them with an underscore (_) to prevent reprocessing.
Time Zones: The script handles time zones by ensuring all datetime objects are timezone-aware. If the time zone information is missing, it assumes the local time zone.
Date Formats: The script is flexible with date formats, using dateutil.parser.parse to handle various date and time representations.
Error Handling: The script includes warnings and error messages to help identify and troubleshoot issues with data parsing or file processing.
Invalid Date Formats: If you receive warnings about invalid date formats, ensure that your JSON files contain date strings in a recognizable format.
No Files Found: If the script reports that no files were found, verify that the file filter matches the filenames in the input folder.
Permission Issues: If the script cannot read or write files, check the permissions of the input and output directories.
Multiple Sources Detected: If a file contains entries from more than one source, the script will skip it and list the sources. Re-run with -u "<source name>" to process only that source.
If you wish to contribute to the script or report issues, please feel free to submit pull requests or open issues on the repository where this script is hosted.
This script is provided as-is without any warranty. Use it at your own risk. The author is not responsible for any damage or data loss resulting from its use.