serializers.py

        source="contributors",
        help_text="`Host` IDs that contributed to an episode.",
    )
    image_id = serializers.PrimaryKeyRelatedField(
        queryset=Image.objects.all(),
        required=False,
        allow_null=True,
        source="image",
        help_text="`Image` ID.",
    )
    language_ids = serializers.PrimaryKeyRelatedField(
        allow_null=True,
        many=True,
        queryset=Language.objects.all(),
        required=False,
        source="language",
        help_text="Array of `Language` IDs.",
    )
    links = NoteLinkSerializer(many=True, required=False, help_text="Array of `Link` objects.")
    playlist_id = serializers.IntegerField(required=False, help_text="Array of `Playlist` IDs.")
    tags = JSONSchemaField(tags_json_schema, required=False, help_text="Tags of the Note.")
    timeslot_id = serializers.PrimaryKeyRelatedField(
        queryset=TimeSlot.objects.all(),
        required=False,
        source="timeslot",
        help_text="`Timeslot` ID.",
    )
    topic_ids = serializers.PrimaryKeyRelatedField(
        allow_null=True,
        many=True,
        queryset=Topic.objects.all(),
        required=False,
        source="topic",
        help_text="Array of `Topic`IDs.",
    )

    class Meta:
        model = Note
        read_only_fields = (
            "id",
            "created_at",
            "created_by",
            "updated_at",
            "updated_by",
        )
        fields = (
            "cba_id",
            "content",
            "contributor_ids",
            "id",
            "image_id",
            "language_ids",
            "links",
            "playlist_id",
            "summary",
            "tags",
            "timeslot_id",
            "title",
            "topic_ids",
        ) + read_only_fields

    def create(self, validated_data):
        """Create and return a new Note instance, given the validated data."""

        links_data = validated_data.pop("links", [])

        show = validated_data["timeslot"].schedule.show
        user = self.context.get("request").user
        user_is_owner = user in show.owners.all()

        # Having the create_note permission overrides the ownership
        if not (
            user.has_perm("program.create_note")
            or (user.has_perm("program.add_note") and user_is_owner)
        ):
            raise exceptions.PermissionDenied(detail="You are not allowed to create this note.")

        # we derive `contributors`, `language` and `topic` from the Show's values if not set
        contributors = validated_data.pop("contributors", show.hosts.values_list("id", flat=True))
        language = validated_data.pop("language", show.language.values_list("id", flat=True))
        topic = validated_data.pop("topic", show.topic.values_list("id", flat=True))

        # optional foreign key
        validated_data["image"] = validated_data.pop("image", None)

        try:
            note = Note.objects.create(
                created_by=self.context.get("request").user.username,
                **validated_data,
            )
        except IntegrityError:
            raise exceptions.ValidationError(
                code="duplicate", detail="note for this timeslot already exists."
            )
        else:
            note.contributors.set(contributors)
            note.language.set(language)
            note.topic.set(topic)

            # optional nested objects
            for link_data in links_data:
                NoteLink.objects.create(note=note, **link_data)

            note.save()

            return note

    def update(self, instance, validated_data):
        """Update and return an existing Note instance, given the validated data."""

        user = self.context.get("request").user
        user_is_owner = user in instance.timeslot.schedule.show.owners.all()

        # Having the update_note permission overrides the ownership
        if not (
            user.has_perm("program.update_note")
            or (user.has_perm("program.change_note") and user_is_owner)
        ):
            raise exceptions.PermissionDenied(detail="You are not allowed to update this note.")

        if "cba_id" in validated_data:
            instance.cba_id = validated_data.get("cba_id")

        if "content" in validated_data:
            instance.content = validated_data.get("content")

        if "image" in validated_data:
            instance.image = validated_data.get("image")

        if "summary" in validated_data:
            instance.summary = validated_data.get("summary")

        if "timeslot" in validated_data:
            instance.timeslot = validated_data.get("timeslot")

        if "tags" in validated_data:
            instance.tags = validated_data.get("tags")

        if "title" in validated_data:
            instance.title = validated_data.get("title")

        # optional many-to-many
        if "contributors" in validated_data:
            instance.contributors.set(validated_data.get("contributors", []))

        if "language" in validated_data:
            instance.language.set(validated_data.get("language", []))

        # Only update this field if the user has the update_note permission, ignore otherwise
        if "topic" in validated_data and user.has_perm("program.update_note"):
            instance.topic.set(validated_data.get("topic", []))

        # optional nested objects
        if "links" in validated_data:
            instance = delete_links(instance)

            for link_data in validated_data.get("links"):
                NoteLink.objects.create(note=instance, **link_data)

        instance.updated_by = self.context.get("request").user.username

        instance.save()

        return instance


class RadioCBASettings(TypedDict):
    api_key: NotRequired[str]
    domains: list[str]


class ProgrammeFallback(TypedDict):
    default_pool: Literal["fallback"] | None
    show_id: int | None


class MicroProgramme(TypedDict):
    show_id: int | None


class RadioProgrammeSettings(TypedDict):
    fallback: ProgrammeFallback
    micro: MicroProgramme


class PlayoutPools(TypedDict):
    fallback: str | None


class RadioPlayoutSettings(TypedDict):
    line_in_channels: dict[str, str]
    pools: PlayoutPools


class RadioStationSettings(TypedDict):
    name: str
    logo_id: int | None
    website: str


class ImageFrame(TypedDict):
    aspect_ratio: tuple[int, int]
    shape: Literal["rect", "round"]


class ImageRequirements(TypedDict):
    frame: ImageFrame


# done this way, because the keys have dots (".")
RadioImageRequirementsSettings = TypedDict(
    "RadioImageRequirementsSettings",
    {
        "host.image": ImageRequirements,
        "note.image": ImageRequirements,
        "show.image": ImageRequirements,
        "show.logo": ImageRequirements,
    },
)


class RadioSettingsSerializer(serializers.ModelSerializer):
    cba = serializers.SerializerMethodField()
    image_requirements = serializers.SerializerMethodField()
    playout = serializers.SerializerMethodField()
    programme = serializers.SerializerMethodField()
    station = serializers.SerializerMethodField()

    class Meta:
        fields = read_only_fields = (
            "id",
            "cba",
            "image_requirements",
            "playout",
            "programme",
            "station",
        )
        model = RadioSettings

    def get_cba(self, obj) -> RadioCBASettings:
        if self.context.get("request").user.is_authenticated:
            return {
                "api_key": obj.cba_api_key,
                "domains": obj.cba_domains,
            }
        else:
            return {"domains": obj.cba_domains}

    @staticmethod
    def get_image_requirements(obj) -> RadioImageRequirementsSettings:
        def get_aspect_ration(field) -> tuple[int, int]:
            """return the tuple of ints representing the aspect ratio of the image."""

            values = field.split(":")

            return int(values[0]), int(values[1])

        aspect_ratios = {
            "host.image": get_aspect_ration(obj.host_image_aspect_ratio),
            "note.image": get_aspect_ration(obj.note_image_aspect_ratio),
            "show.image": get_aspect_ration(obj.show_image_aspect_ratio),
            "show.logo": get_aspect_ration(obj.show_logo_aspect_ratio),
        }

        return {
            "host.image": {
                "frame": {
                    "aspect_ratio": aspect_ratios["host.image"],
                    "shape": obj.host_image_shape,
                }
            },
            "note.image": {
                "frame": {
                    "aspect_ratio": aspect_ratios["note.image"],
                    "shape": obj.host_image_shape,
                }
            },
            "show.image": {
                "frame": {
                    "aspect_ratio": aspect_ratios["show.image"],
                    "shape": obj.host_image_shape,
                }
            },
            "show.logo": {
                "frame": {
                    "aspect_ratio": aspect_ratios["show.logo"],
                    "shape": obj.host_image_shape,
                }
            },
        }

    @staticmethod
    def get_programme(obj) -> RadioProgrammeSettings:
        return {
            "micro": {"show_id": obj.micro_show.id if obj.micro_show else None},
            "fallback": {
                "show_id": obj.fallback_show.id if obj.fallback_show else None,
                "default_pool": "fallback",
            },
        }

    @staticmethod
    def get_playout(obj) -> RadioPlayoutSettings:
        return {
            "line_in_channels": obj.line_in_channels,
            "pools": {
                "fallback": obj.fallback_default_pool,
            },
        }

    @staticmethod
    def get_station(obj) -> RadioStationSettings:
        return {
            "name": obj.station_name,
            "logo_id": obj.station_logo.id if obj.station_logo else None,
            "website": obj.station_website,
        }


class PlayoutSerializer(serializers.Serializer):
    end = serializers.DateTimeField()
    id = serializers.IntegerField()
    is_virtual = serializers.BooleanField()
    playlist_id = serializers.IntegerField(allow_null=True)
    repetition_of_id = serializers.IntegerField(allow_null=True)
    schedule_default_playlist_id = serializers.IntegerField(allow_null=True)
    schedule_id = serializers.IntegerField()
    show_default_playlist_id = serializers.IntegerField(required=False)
    show_id = serializers.IntegerField()
    show_name = serializers.CharField()
    start = serializers.DateTimeField()


class DayScheduleSerializer(serializers.Serializer):
    end = serializers.DateTimeField()
    is_virtual = serializers.BooleanField()
    show_id = serializers.IntegerField()
    start = serializers.DateTimeField()
    show_name = serializers.CharField()