{"id":17036762,"url":"https://github.com/faroit/commonfate","last_synced_at":"2025-07-05T20:41:27.144Z","repository":{"id":62564140,"uuid":"44346635","full_name":"faroit/commonfate","owner":"faroit","description":null,"archived":false,"fork":false,"pushed_at":"2020-02-27T23:18:07.000Z","size":2458,"stargazers_count":17,"open_issues_count":1,"forks_count":5,"subscribers_count":2,"default_branch":"master","last_synced_at":"2024-05-19T05:03:15.755Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"bsd-3-clause","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/faroit.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.txt","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2015-10-15T21:28:16.000Z","updated_at":"2023-04-27T06:24:38.000Z","dependencies_parsed_at":"2022-11-03T16:00:35.213Z","dependency_job_id":null,"html_url":"https://github.com/faroit/commonfate","commit_stats":null,"previous_names":["aliutkus/commonfate"],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fcommonfate","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fcommonfate/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fcommonfate/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/faroit%2Fcommonfate/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/faroit","download_url":"https://codeload.github.com/faroit/commonfate/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248571836,"owners_count":21126522,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-10-14T08:51:52.188Z","updated_at":"2025-04-12T13:20:32.968Z","avatar_url":"https://github.com/faroit.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Common Fate Transform and Model for Python\n\nThis package is a python implementation of the _Common Fate Transform and Model_ to be used for audio source separation as described in [an ICASSP 2016 paper \"Common Fate Model for Unison source Separation\"](https://hal.archives-ouvertes.fr/hal-01248012/file/common_fate_icassp2016.pdf).\n\n### Common Fate Transform\n\n![cft](https://cloud.githubusercontent.com/assets/72940/13906318/5de230a0-ef0e-11e5-8447-3a2f1600a22a.png)\n\nThe Common Fate Transform is based on a signal representation that divides a complex spectrogram into a grid of patches of arbitrary size. These complex patches are then processed by a two-dimensional discrete Fourier transform, forming a tensor representation which reveals spectral and temporal modulation textures.\n\n### Common Fate Model\n\n![cfm](https://cloud.githubusercontent.com/assets/72940/13906456/402211d6-ef11-11e5-8103-12944f5404f4.png)\n\nAn adapted factorization model similar to the PARAFAC/CANDECOMP factorisation allows to decompose the _common fate transform_ tesnor into different time-varying harmonic sources based on their particular common modulation profile: hence the name Common Fate Model.\n\n## Usage\n\nSee the full API documentation at http://aliutkus.github.io/commonfate.\n\n### Applying the Common Fate Transform\n\n```python\nimport commonfate\n\n# # forward transform\n\n# STFT Parameters\n\nframelength = 1024\nhopsize = 256\nX = commonfate.transform.forward(signal, framelength, hopsize)\n\n# Patch Parameters\nW = (32, 48)\nmhop = (16, 24)\n\nZ = commonfate.transform.forward(X, W, mhop, real=False)\n\n# inverse transform of cft\nY = commonfate.transform.inverse(\n    Z, fdim=2, hop=mhop, shape=X.shape, real=False\n)\n# back to time domain\ny = commonfate.transform.inverse(\n    Y, fdim=1, hop=hopsize, shape=x.shape\n)\n\n```\n\n### Fitting the Common Fate Model\n\n```python\nimport commonfate\n\n# initialiase and fit the common fate model\ncfm = commonfate.model.CFM(z, nb_components=10, nb_iter=100).fit()\n\n# get the fitted factors\n(A, H, C) = cfm.factors\n\n# returns the of z approximation using the fitted factors\nz_hat = cfm.approx()\n```\n\n### Decompose an audio signal using CFT and CFM\n\n_commonfate_ has a built-in wrapper which computes the _Common Fate Transform_,\nfits the model according to the _Common Fate Model_ and return the synthesised\ntime domain signal components obtained through wiener / soft mask filtering.\n\nThe following example requires to install [pysoundfile](https://github.com/bastibe/PySoundFile).\n\n```python\nimport commonfate\nimport soundfile as sf\n\n# loading signal\n(audio, fs) = sf.read(filename, always_2d=True)\n\n# decomposes the audio signal into\n# (nb_components, nb_samples, nb_channels)\ncomponents = decompose.process(\n    audio,\n    nb_iter=100,\n    nb_components=10,\n    n_fft=1024,\n    n_hop=256,\n    cft_patch=(32, 48),\n    cft_hop=(16, 24)\n)\n\n# write out the third component to wave file\nsf.write(\n    \"comp_3.wav\",\n    components[2, ...],\n    fs\n)\n```\n\n## Optimisations\n\nThe current common fate model implementation makes heavily use of the [Einstein Notation](https://en.wikipedia.org/wiki/Einstein_notation). We use the [numpy ```einsum``` module](http://docs.scipy.org/doc/numpy-1.10.0/reference/generated/numpy.einsum.html\n) which can be slow on large tensors. To speed up the computation time we recommend to install [Daniel Smith's ```opt_einsum``` package](https://github.com/dgasmith/opt_einsum).\n\n##### Installation via pip\n```bash\npip install -e 'git+https://github.com/dgasmith/opt_einsum.git#egg=opt_einsum'\n```\n\n_commonfate_ automatically detects if the package is installed.\n\n## References\n\nYou can download and read the paper [here](https://hal.archives-ouvertes.fr/hal-01248012/file/common_fate_icassp2016.pdf).\nIf you use this package, please reference to the following publication:\n\n```tex\n@inproceedings{stoeter2016cfm,\n  TITLE = {{Common Fate Model for Unison source Separation}},\n  AUTHOR = {St{\\\"o}ter, Fabian-Robert and Liutkus, Antoine and Badeau, Roland and Edler, Bernd and Magron, Paul},\n  BOOKTITLE = {{41st International Conference on Acoustics, Speech and Signal Processing (ICASSP)}},\n  ADDRESS = {Shanghai, China},\n  PUBLISHER = {{IEEE}},\n  SERIES = {Proceedings of the 41st International Conference on Acoustics, Speech and Signal Processing (ICASSP)},\n  YEAR = {2016},\n  KEYWORDS = {Non-Negative tensor factorization ; Sound source separation ; Common Fate Model},\n}\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaroit%2Fcommonfate","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffaroit%2Fcommonfate","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffaroit%2Fcommonfate/lists"}